@syengup/friday-channel-next 0.1.22 → 0.1.23

package/dist/src/channel-actions.js

@@ -2,6 +2,7 @@ import crypto from "node:crypto";
 import fs from "node:fs";
 import { sseEmitter } from "./sse/emitter.js";
 import { guessMimeType } from "./http/handlers/files.js";
+import { downloadRemoteMedia, isHttpUrl } from "./media-fetch.js";
 import { getRunRoute } from "./run-metadata.js";
 import { resolveHistorySessionKeyForFridayDevice } from "./friday-session.js";
 const DISCOVERY = {
@@ -24,6 +25,9 @@ function pickString(params, keys) {
     return "";
 }
 async function readMediaFile(mediaPath, ctx) {
+    if (isHttpUrl(mediaPath)) {
+        return downloadRemoteMedia(mediaPath);
+    }
     if (ctx.mediaReadFile) {
         try {
             const buffer = await ctx.mediaReadFile(mediaPath);
@@ -44,7 +48,7 @@ async function readMediaFile(mediaPath, ctx) {
 async function handleSend(ctx) {
     const to = pickString(ctx.params, ["to", "target"]).toUpperCase();
     const text = pickString(ctx.params, ["message", "text", "content"]);
-    const mediaPath = pickString(ctx.params, ["media", "path", "filePath", "fileUrl"]);
+    const mediaPath = pickString(ctx.params, ["media", "url", "path", "filePath", "fileUrl"]);
     const caption = pickString(ctx.params, ["caption"]);
     if (!to) {
         return { ok: false, error: "Missing required param: to" };

package/dist/src/channel.js

@@ -13,6 +13,7 @@ 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 { resolveFridayDeviceIdForOutbound, resolveHistorySessionKeyForFridayDevice, } from "./friday-session.js";
 import { getRunRoute } from "./run-metadata.js";
 import { getLastFridayInboundAt } from "./friday-inbound-stats.js";
@@ -212,12 +213,20 @@ export const fridayNextChannelPlugin = createChatChannelPlugin({
                 };
             }
             let buffer = null;
+            let downloadedMimeType = null;
             if (ctx.mediaReadFile) {
                 try {
                     buffer = await ctx.mediaReadFile(mediaUrl);
                 }
                 catch {
-                    // fall through to fs
+                    // fall through to remote download / fs
+                }
+            }
+            if (!buffer && isHttpUrl(mediaUrl)) {
+                const remote = await downloadRemoteMedia(mediaUrl);
+                if (remote) {
+                    buffer = remote.buffer;
+                    downloadedMimeType = remote.mimeType;
                 }
             }
             if (!buffer) {
@@ -230,7 +239,7 @@ export const fridayNextChannelPlugin = createChatChannelPlugin({
                 }
             }
             if (buffer) {
-                const mimeType = guessMimeType(mediaUrl);
+                const mimeType = downloadedMimeType ?? guessMimeType(mediaUrl);
                 const saved = await saveMediaBuffer(buffer, mimeType, "inbound");
                 if (saved.id) {
                     const fileUrl = `/friday-next/files/${encodeURIComponent(saved.id)}`;

package/dist/src/friday-session.js

@@ -1,11 +1,11 @@
 import { sseEmitter } from "./sse/emitter.js";
 import { getFridayAgentForwardRuntime } from "./agent-forward-runtime.js";
-import { toSessionStoreKey, agentIdFromSessionKey } from "./session/session-manager.js";
+import { toSessionStoreKey } from "./session/session-manager.js";
 import { getOpenClawAgentRunContext } from "./agent-run-context-bridge.js";
 import { observeAgentEventForActiveRuns } from "./agent/active-runs.js";
 import { getRunMetadata, ingestAgentEventMetadata } from "./run-metadata.js";
 import { consumeRunUsage } from "./agent/run-usage-accumulator.js";
-import { buildSessionUsageSnapshot } from "./session-usage-snapshot.js";
+import { readSessionUsageSnapshotFromStore } from "./session-usage-store.js";
 import { lookupByRunId, registerSessionKeyForRun, registerSpawnIntent, consumeSpawnIntent, ensureSubagentFromSpawnTool, registerEnded as registerSubagentEnded, } from "./agent/subagent-registry.js";
 /** Last `data.text` per run for `stream: "thinking"` — OpenClaw core may send cumulative `delta`; we rewrite true increments for the app. */
 const lastThinkingTextByRun = new Map();
@@ -143,25 +143,6 @@ function mergeRunMetadataIntoLifecycleEnd(runId, base) {
         return base;
     return { ...base, ...extra };
 }
-function tryReadSessionUsageFromStore(sessionKeyForStore) {
-    const access = getFridayAgentForwardRuntime();
-    if (!access)
-        return undefined;
-    try {
-        const cfg = access.getConfig();
-        const storeConfig = cfg?.session?.store;
-        const canonical = toSessionStoreKey(sessionKeyForStore);
-        const storePath = access.resolveStorePath(storeConfig, { agentId: agentIdFromSessionKey(canonical) });
-        const store = access.loadSessionStore(storePath, { skipCache: true });
-        const entry = store[canonical] ?? store[sessionKeyForStore.trim()];
-        if (!entry || typeof entry !== "object")
-            return undefined;
-        return buildSessionUsageSnapshot(entry);
-    }
-    catch {
-        return undefined;
-    }
-}
 function buildSessionUsageFromRunMetadata(runId) {
     const meta = getRunMetadata(runId);
     if (!meta)
@@ -425,7 +406,7 @@ export function forwardAgentEventRaw(evt) {
         // llm_output data is per-run; store is cumulative across rounds.
         setTimeout(() => {
             let data = outgoingData;
-            const storeUsage = tryReadSessionUsageFromStore(sk);
+            const storeUsage = readSessionUsageSnapshotFromStore(sk);
             const llmUsage = consumeRunUsage(evt.runId);
             const memUsage = buildSessionUsageFromRunMetadata(evt.runId);
             let usage;

package/dist/src/http/handlers/history-messages.js

@@ -14,6 +14,7 @@ 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";
+import { readSessionUsageSnapshotFromStore } from "../../session-usage-store.js";
 const DEFAULT_LIMIT = 200;
 const MAX_LIMIT = 1000;
 function resolveSubagentApi() {
@@ -86,6 +87,12 @@ export async function handleHistoryMessages(req, res) {
         delete message.mediaPaths;
     }
     const sessionId = resolveSessionId(sessionKey);
+    // Cumulative session-usage snapshot (model + context window/used) read from the
+    // session store — the SAME source the live `lifecycle.end` frame uses. The
+    // transcript carries per-message model/tokens but NOT the context-window figures,
+    // so the app stamps this snapshot onto the latest assistant turn on rebuild to
+    // keep the nav-bar context ring correct (and surviving app restarts).
+    const sessionUsage = readSessionUsageSnapshotFromStore(sessionKey);
     res.statusCode = 200;
     res.setHeader("Content-Type", "application/json");
     res.end(JSON.stringify({
@@ -95,6 +102,7 @@ export async function handleHistoryMessages(req, res) {
         ...(sessionId ? { sessionId } : {}),
         totalMessages: messages.length,
         messages,
+        ...(sessionUsage ? { sessionUsage } : {}),
     }));
     return true;
 }

package/dist/src/media-fetch.d.ts

@@ -0,0 +1,13 @@
+export declare function isHttpUrl(value: string): boolean;
+/**
+ * Download an http/https URL into a buffer. Returns null on any failure (non-2xx, oversize, timeout,
+ * network error) so callers degrade to text-only rather than throwing.
+ *
+ * The mime type prefers the response `Content-Type`, falling back to the URL extension. It is only a
+ * hint — `saveMediaBuffer` re-detects the real type from the buffer's magic bytes, so links without
+ * an extension (e.g. `picsum.photos/600/400`) still land with the correct file type.
+ */
+export declare function downloadRemoteMedia(url: string): Promise<{
+    buffer: Buffer;
+    mimeType: string;
+} | null>;

package/dist/src/media-fetch.js

@@ -0,0 +1,53 @@
+import { guessMimeType } from "./http/handlers/files.js";
+/**
+ * Remote (http/https) media download for the `message` tool and outbound sendMedia.
+ *
+ * The agent often sends attachments as a direct link (`url: "https://.../foo.jpg"`) rather than a
+ * local file path. The gateway can reach that link even when the user's device can't (ATS, foreign
+ * TLS, intranet / geo differences), so we download it server-side and re-publish it through the
+ * gateway's `/friday-next/files/` route — identical to the local-file path. This keeps the app's
+ * download story uniform (always talks to the trusted gateway host with a bearer token).
+ */
+const MAX_REMOTE_MEDIA_BYTES = 25 * 1024 * 1024; // 25MB
+const REMOTE_MEDIA_TIMEOUT_MS = 20_000;
+export function isHttpUrl(value) {
+    return /^https?:\/\//i.test(value.trim());
+}
+/**
+ * Download an http/https URL into a buffer. Returns null on any failure (non-2xx, oversize, timeout,
+ * network error) so callers degrade to text-only rather than throwing.
+ *
+ * The mime type prefers the response `Content-Type`, falling back to the URL extension. It is only a
+ * hint — `saveMediaBuffer` re-detects the real type from the buffer's magic bytes, so links without
+ * an extension (e.g. `picsum.photos/600/400`) still land with the correct file type.
+ */
+export async function downloadRemoteMedia(url) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), REMOTE_MEDIA_TIMEOUT_MS);
+    try {
+        const res = await fetch(url, { redirect: "follow", signal: controller.signal });
+        if (!res.ok)
+            return null;
+        const declaredLength = Number(res.headers.get("content-length") ?? "");
+        if (Number.isFinite(declaredLength) && declaredLength > MAX_REMOTE_MEDIA_BYTES) {
+            return null;
+        }
+        const buffer = Buffer.from(await res.arrayBuffer());
+        if (!buffer.length || buffer.length > MAX_REMOTE_MEDIA_BYTES)
+            return null;
+        const headerMime = res.headers.get("content-type")?.split(";")[0]?.trim().toLowerCase();
+        const extMime = guessMimeType(url);
+        const mimeType = headerMime && headerMime !== "application/octet-stream"
+            ? headerMime
+            : extMime !== "application/octet-stream"
+                ? extMime
+                : headerMime || "application/octet-stream";
+        return { buffer, mimeType };
+    }
+    catch {
+        return null;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}

package/dist/src/session-usage-store.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Reads the cumulative session-usage snapshot from the OpenClaw session store
+ * (`sessions.json`) for a given Friday session key.
+ *
+ * Shared by two readers:
+ *   - the live terminal-lifecycle forward (`friday-session.ts`), which stamps the
+ *     snapshot onto the `lifecycle.end` frame, and
+ *   - the history endpoint (`http/handlers/history-messages.ts`), which returns it
+ *     alongside the transcript so a rebuild can restore the nav-bar context ring.
+ *
+ * The snapshot is **session-cumulative**, not per-message: `context.windowMax` is
+ * the model's context window and `context.used` is the running session total. The
+ * transcript only carries per-message `model` + `usage.{total,input,output}`; the
+ * context-window figures live only here, in the session store.
+ */
+import type { FridaySessionUsagePayload } from "./session-usage-snapshot.js";
+export declare function readSessionUsageSnapshotFromStore(sessionKeyForStore: string): FridaySessionUsagePayload | undefined;

package/dist/src/session-usage-store.js

@@ -0,0 +1,37 @@
+/**
+ * Reads the cumulative session-usage snapshot from the OpenClaw session store
+ * (`sessions.json`) for a given Friday session key.
+ *
+ * Shared by two readers:
+ *   - the live terminal-lifecycle forward (`friday-session.ts`), which stamps the
+ *     snapshot onto the `lifecycle.end` frame, and
+ *   - the history endpoint (`http/handlers/history-messages.ts`), which returns it
+ *     alongside the transcript so a rebuild can restore the nav-bar context ring.
+ *
+ * The snapshot is **session-cumulative**, not per-message: `context.windowMax` is
+ * the model's context window and `context.used` is the running session total. The
+ * transcript only carries per-message `model` + `usage.{total,input,output}`; the
+ * context-window figures live only here, in the session store.
+ */
+import { getFridayAgentForwardRuntime } from "./agent-forward-runtime.js";
+import { toSessionStoreKey, agentIdFromSessionKey } from "./session/session-manager.js";
+import { buildSessionUsageSnapshot } from "./session-usage-snapshot.js";
+export function readSessionUsageSnapshotFromStore(sessionKeyForStore) {
+    const access = getFridayAgentForwardRuntime();
+    if (!access)
+        return undefined;
+    try {
+        const cfg = access.getConfig();
+        const storeConfig = cfg?.session?.store;
+        const canonical = toSessionStoreKey(sessionKeyForStore);
+        const storePath = access.resolveStorePath(storeConfig, { agentId: agentIdFromSessionKey(canonical) });
+        const store = access.loadSessionStore(storePath, { skipCache: true });
+        const entry = store[canonical] ?? store[sessionKeyForStore.trim()];
+        if (!entry || typeof entry !== "object")
+            return undefined;
+        return buildSessionUsageSnapshot(entry);
+    }
+    catch {
+        return undefined;
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@syengup/friday-channel-next",
-  "version": "0.1.22",
+  "version": "0.1.23",
   "description": "OpenClaw Friday Next Apple channel plugin",
   "license": "MIT",
   "type": "module",
@@ -12,15 +12,6 @@
     "tsconfig.json",
     "openclaw.plugin.json"
   ],
-  "scripts": {
-    "build": "tsc -p tsconfig.json",
-    "prepublishOnly": "pnpm build && rm -rf dist/attachments",
-    "test": "npm run test:unit && npm run test:e2e",
-    "test:unit": "vitest run",
-    "test:e2e": "vitest run --config vitest.e2e.config.ts",
-    "test:smoke": "node scripts/e2e-smoke.mjs",
-    "test:msg-live": "node scripts/message-roundtrip-live.mjs"
-  },
   "bin": {
     "friday-channel-next": "install.js"
   },
@@ -66,5 +57,13 @@
     "typescript": "^6.0.3",
     "vitest": "^4.1.5",
     "zod": "^4.3.6"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "npm run test:unit && npm run test:e2e",
+    "test:unit": "vitest run",
+    "test:e2e": "vitest run --config vitest.e2e.config.ts",
+    "test:smoke": "node scripts/e2e-smoke.mjs",
+    "test:msg-live": "node scripts/message-roundtrip-live.mjs"
   }
-}
+}

package/src/channel-actions.test.ts

@@ -1,7 +1,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import { EventEmitter } from "node:events";
-import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import { handleMessageAction } from "./channel-actions.js";
 import { sseEmitter } from "./sse/emitter.js";
 import { setOfflineQueueBaseDirForTest } from "./sse/offline-queue.js";
@@ -60,6 +60,7 @@ describe("channel-actions handleSend sessionKey routing", () => {
   });
 
   afterEach(() => {
+    vi.unstubAllGlobals();
     setOfflineQueueBaseDirForTest(null);
     removeTempHistoryDir(historyDir);
   });
@@ -95,6 +96,40 @@ describe("channel-actions handleSend sessionKey routing", () => {
     expect(media?.data.deviceId).toBe(deviceId);
   });
 
+  it("send media via an https `url` direct link downloads it and emits op:media", async () => {
+    const deviceId = "DEV-ACT-URL";
+    const runId = "run-act-url";
+    const appSession = "agent:operator:friday:direct:dev-act-url:1780561609";
+    registerRunRoute({ runId, deviceId, sessionKey: appSession });
+    sseEmitter.trackDeviceForRun(deviceId, runId);
+    const res = connect(deviceId);
+
+    // 8-byte PNG magic header so saveMediaBuffer's magic-byte detection recognizes an image.
+    const pngBytes = new Uint8Array([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a, 0x00, 0x01]);
+    const directLink = "https://picsum.photos/600/400";
+    const fetchMock = vi.fn(async () =>
+      new Response(pngBytes, { status: 200, headers: { "content-type": "image/png" } }),
+    );
+    vi.stubGlobal("fetch", fetchMock);
+
+    const result = await handleMessageAction({
+      action: "send",
+      // The agent sends a direct link via the `url` param, not `media`.
+      params: { to: deviceId, message: "直链图来了", url: directLink },
+      sessionKey: "agent:operator:main",
+    });
+
+    expect((result as { ok?: boolean }).ok).toBe(true);
+    expect(fetchMock).toHaveBeenCalledWith(directLink, expect.anything());
+
+    const frames = parseOutboundFrames(res);
+    const media = frames.find((f) => f.type === "outbound" && f.data.op === "media");
+    expect(media).toBeTruthy();
+    expect(String(media?.data.mediaUrl)).toMatch(/^\/friday-next\/files\//);
+    expect((media?.data.ctx as { originalMediaUrl?: string })?.originalMediaUrl).toBe(directLink);
+    expect(media?.data.sessionKey).toBe(appSession);
+  });
+
   it("falls back to ctx.sessionKey when the device has no active run-route", async () => {
     const deviceId = "DEV-ACT-2";
     const res = connect(deviceId);

package/src/channel-actions.ts

@@ -2,6 +2,7 @@ import crypto from "node:crypto";
 import fs from "node:fs";
 import { sseEmitter } from "./sse/emitter.js";
 import { guessMimeType } from "./http/handlers/files.js";
+import { downloadRemoteMedia, isHttpUrl } from "./media-fetch.js";
 import { getRunRoute } from "./run-metadata.js";
 import { resolveHistorySessionKeyForFridayDevice } from "./friday-session.js";
 
@@ -39,6 +40,9 @@ async function readMediaFile(
   mediaPath: string,
   ctx: MessageActionCtx,
 ): Promise<{ buffer: Buffer; mimeType: string } | null> {
+  if (isHttpUrl(mediaPath)) {
+    return downloadRemoteMedia(mediaPath);
+  }
   if (ctx.mediaReadFile) {
     try {
       const buffer = await ctx.mediaReadFile(mediaPath);
@@ -58,7 +62,7 @@ async function readMediaFile(
 async function handleSend(ctx: MessageActionCtx): Promise<unknown> {
   const to = pickString(ctx.params, ["to", "target"]).toUpperCase();
   const text = pickString(ctx.params, ["message", "text", "content"]);
-  const mediaPath = pickString(ctx.params, ["media", "path", "filePath", "fileUrl"]);
+  const mediaPath = pickString(ctx.params, ["media", "url", "path", "filePath", "fileUrl"]);
   const caption = pickString(ctx.params, ["caption"]);
 
   if (!to) {

package/src/channel.ts

@@ -15,6 +15,7 @@ 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 {
   resolveFridayDeviceIdForOutbound,
   resolveHistorySessionKeyForFridayDevice,
@@ -245,12 +246,21 @@ export const fridayNextChannelPlugin = createChatChannelPlugin({
         }
 
         let buffer: Buffer | null = null;
+        let downloadedMimeType: string | null = null;
 
         if (ctx.mediaReadFile) {
           try {
             buffer = await ctx.mediaReadFile(mediaUrl);
           } catch {
-            // fall through to fs
+            // fall through to remote download / fs
+          }
+        }
+
+        if (!buffer && isHttpUrl(mediaUrl)) {
+          const remote = await downloadRemoteMedia(mediaUrl);
+          if (remote) {
+            buffer = remote.buffer;
+            downloadedMimeType = remote.mimeType;
           }
         }
 
@@ -264,7 +274,7 @@ export const fridayNextChannelPlugin = createChatChannelPlugin({
         }
 
         if (buffer) {
-          const mimeType = guessMimeType(mediaUrl);
+          const mimeType = downloadedMimeType ?? guessMimeType(mediaUrl);
           const saved = await saveMediaBuffer(buffer, mimeType, "inbound");
           if (saved.id) {
             const fileUrl = `/friday-next/files/${encodeURIComponent(saved.id)}`;

package/src/friday-session.ts

@@ -1,12 +1,12 @@
 import { sseEmitter } from "./sse/emitter.js";
 import { getFridayAgentForwardRuntime } from "./agent-forward-runtime.js";
-import { toSessionStoreKey, agentIdFromSessionKey } from "./session/session-manager.js";
+import { toSessionStoreKey } from "./session/session-manager.js";
 import { getOpenClawAgentRunContext } from "./agent-run-context-bridge.js";
 import { observeAgentEventForActiveRuns } from "./agent/active-runs.js";
 import { getRunMetadata, ingestAgentEventMetadata } from "./run-metadata.js";
 import { consumeRunUsage } from "./agent/run-usage-accumulator.js";
-import { buildSessionUsageSnapshot } from "./session-usage-snapshot.js";
 import type { FridaySessionUsagePayload } from "./session-usage-snapshot.js";
+import { readSessionUsageSnapshotFromStore } from "./session-usage-store.js";
 import {
   lookupByRunId,
   registerSessionKeyForRun,
@@ -178,23 +178,6 @@ function mergeRunMetadataIntoLifecycleEnd(
   return { ...base, ...extra };
 }
 
-function tryReadSessionUsageFromStore(sessionKeyForStore: string): FridaySessionUsagePayload | undefined {
-  const access = getFridayAgentForwardRuntime();
-  if (!access) return undefined;
-  try {
-    const cfg = access.getConfig() as { session?: { store?: string } } | null | undefined;
-    const storeConfig = cfg?.session?.store;
-    const canonical = toSessionStoreKey(sessionKeyForStore);
-    const storePath = access.resolveStorePath(storeConfig, { agentId: agentIdFromSessionKey(canonical) });
-    const store = access.loadSessionStore(storePath, { skipCache: true }) as Record<string, Record<string, unknown>>;
-    const entry = store[canonical] ?? store[sessionKeyForStore.trim()];
-    if (!entry || typeof entry !== "object") return undefined;
-    return buildSessionUsageSnapshot(entry);
-  } catch {
-    return undefined;
-  }
-}
-
 function buildSessionUsageFromRunMetadata(runId: string): FridaySessionUsagePayload | undefined {
   const meta = getRunMetadata(runId);
   if (!meta) return undefined;
@@ -487,7 +470,7 @@ export function forwardAgentEventRaw(evt: ForwardAgentEventArgs): void {
     // llm_output data is per-run; store is cumulative across rounds.
     setTimeout(() => {
       let data = outgoingData;
-      const storeUsage = tryReadSessionUsageFromStore(sk);
+      const storeUsage = readSessionUsageSnapshotFromStore(sk);
       const llmUsage = consumeRunUsage(evt.runId);
       const memUsage = buildSessionUsageFromRunMetadata(evt.runId);
       let usage: FridaySessionUsagePayload | undefined;

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

@@ -114,6 +114,45 @@ describe("handleHistoryMessages", () => {
     expect(body.messages[1].text).toBe("hello");
   });
 
+  it("returns the cumulative sessionUsage snapshot from the store", async () => {
+    const file = writeTranscript("usage.jsonl", [
+      { type: "message", id: "u1", message: { role: "user", content: "hi" } },
+      { type: "message", id: "a1", message: { role: "assistant", content: [{ type: "text", text: "yo" }], model: "openai/gpt-4" } },
+    ]);
+    setForward({
+      "agent:main:main": {
+        sessionId: "s",
+        sessionFile: file,
+        model: "openai/gpt-4",
+        totalTokens: 12_480,
+        contextTokens: 128_000,
+        inputTokens: 9_000,
+        outputTokens: 3_480,
+      },
+    });
+
+    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.sessionUsage).toBeDefined();
+    expect(body.sessionUsage.modelId).toBe("openai/gpt-4");
+    expect(body.sessionUsage.context).toEqual({ windowMax: 128_000, used: 12_480 });
+    expect(body.sessionUsage.tokens.total).toBe(12_480);
+  });
+
+  it("omits sessionUsage when the store has no entry", async () => {
+    const file = writeTranscript("nousage.jsonl", [
+      { type: "message", id: "u1", message: { role: "user", content: "hi" } },
+    ]);
+    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);
+    const body = JSON.parse(res.body);
+    expect(body.sessionUsage).toBeUndefined();
+  });
+
   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" } },

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

@@ -16,6 +16,7 @@ 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";
+import { readSessionUsageSnapshotFromStore } from "../../session-usage-store.js";
 
 const DEFAULT_LIMIT = 200;
 const MAX_LIMIT = 1000;
@@ -107,6 +108,13 @@ export async function handleHistoryMessages(
 
   const sessionId = resolveSessionId(sessionKey);
 
+  // Cumulative session-usage snapshot (model + context window/used) read from the
+  // session store — the SAME source the live `lifecycle.end` frame uses. The
+  // transcript carries per-message model/tokens but NOT the context-window figures,
+  // so the app stamps this snapshot onto the latest assistant turn on rebuild to
+  // keep the nav-bar context ring correct (and surviving app restarts).
+  const sessionUsage = readSessionUsageSnapshotFromStore(sessionKey);
+
   res.statusCode = 200;
   res.setHeader("Content-Type", "application/json");
   res.end(
@@ -117,6 +125,7 @@ export async function handleHistoryMessages(
       ...(sessionId ? { sessionId } : {}),
       totalMessages: messages.length,
       messages,
+      ...(sessionUsage ? { sessionUsage } : {}),
     }),
   );
   return true;

package/src/media-fetch.test.ts

@@ -0,0 +1,78 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { downloadRemoteMedia, isHttpUrl } from "./media-fetch.js";
+
+describe("isHttpUrl", () => {
+  it("matches http/https links, rejects local paths", () => {
+    expect(isHttpUrl("https://picsum.photos/600/400")).toBe(true);
+    expect(isHttpUrl("http://example.com/a.png")).toBe(true);
+    expect(isHttpUrl("  HTTPS://EXAMPLE.com/a.png ")).toBe(true);
+    expect(isHttpUrl("/tmp/test.jpg")).toBe(false);
+    expect(isHttpUrl("file:///tmp/test.jpg")).toBe(false);
+    expect(isHttpUrl("shot.png")).toBe(false);
+  });
+});
+
+describe("downloadRemoteMedia", () => {
+  afterEach(() => {
+    vi.unstubAllGlobals();
+  });
+
+  it("downloads bytes and prefers the response content-type", async () => {
+    const bytes = new Uint8Array([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+    vi.stubGlobal(
+      "fetch",
+      vi.fn(async () => new Response(bytes, { status: 200, headers: { "content-type": "image/png" } })),
+    );
+
+    const result = await downloadRemoteMedia("https://picsum.photos/600/400");
+    expect(result).toBeTruthy();
+    expect(result?.mimeType).toBe("image/png");
+    expect(result?.buffer.length).toBe(bytes.length);
+  });
+
+  it("falls back to the URL extension when content-type is octet-stream", async () => {
+    const bytes = new Uint8Array([0xff, 0xd8, 0xff, 0xe0]);
+    vi.stubGlobal(
+      "fetch",
+      vi.fn(
+        async () =>
+          new Response(bytes, {
+            status: 200,
+            headers: { "content-type": "application/octet-stream" },
+          }),
+      ),
+    );
+
+    const result = await downloadRemoteMedia("https://cdn.example.com/photo.jpg");
+    expect(result?.mimeType).toBe("image/jpeg");
+  });
+
+  it("returns null on a non-2xx response", async () => {
+    vi.stubGlobal("fetch", vi.fn(async () => new Response("nope", { status: 404 })));
+    expect(await downloadRemoteMedia("https://example.com/missing.png")).toBeNull();
+  });
+
+  it("returns null when the content-length exceeds the cap", async () => {
+    vi.stubGlobal(
+      "fetch",
+      vi.fn(
+        async () =>
+          new Response(new Uint8Array([1, 2, 3]), {
+            status: 200,
+            headers: { "content-type": "image/png", "content-length": String(64 * 1024 * 1024) },
+          }),
+      ),
+    );
+    expect(await downloadRemoteMedia("https://example.com/huge.png")).toBeNull();
+  });
+
+  it("returns null on a network error instead of throwing", async () => {
+    vi.stubGlobal(
+      "fetch",
+      vi.fn(async () => {
+        throw new Error("ECONNREFUSED");
+      }),
+    );
+    expect(await downloadRemoteMedia("https://example.com/x.png")).toBeNull();
+  });
+});

package/src/media-fetch.ts

@@ -0,0 +1,60 @@
+import { guessMimeType } from "./http/handlers/files.js";
+
+/**
+ * Remote (http/https) media download for the `message` tool and outbound sendMedia.
+ *
+ * The agent often sends attachments as a direct link (`url: "https://.../foo.jpg"`) rather than a
+ * local file path. The gateway can reach that link even when the user's device can't (ATS, foreign
+ * TLS, intranet / geo differences), so we download it server-side and re-publish it through the
+ * gateway's `/friday-next/files/` route — identical to the local-file path. This keeps the app's
+ * download story uniform (always talks to the trusted gateway host with a bearer token).
+ */
+
+const MAX_REMOTE_MEDIA_BYTES = 25 * 1024 * 1024; // 25MB
+const REMOTE_MEDIA_TIMEOUT_MS = 20_000;
+
+export function isHttpUrl(value: string): boolean {
+  return /^https?:\/\//i.test(value.trim());
+}
+
+/**
+ * Download an http/https URL into a buffer. Returns null on any failure (non-2xx, oversize, timeout,
+ * network error) so callers degrade to text-only rather than throwing.
+ *
+ * The mime type prefers the response `Content-Type`, falling back to the URL extension. It is only a
+ * hint — `saveMediaBuffer` re-detects the real type from the buffer's magic bytes, so links without
+ * an extension (e.g. `picsum.photos/600/400`) still land with the correct file type.
+ */
+export async function downloadRemoteMedia(
+  url: string,
+): Promise<{ buffer: Buffer; mimeType: string } | null> {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), REMOTE_MEDIA_TIMEOUT_MS);
+  try {
+    const res = await fetch(url, { redirect: "follow", signal: controller.signal });
+    if (!res.ok) return null;
+
+    const declaredLength = Number(res.headers.get("content-length") ?? "");
+    if (Number.isFinite(declaredLength) && declaredLength > MAX_REMOTE_MEDIA_BYTES) {
+      return null;
+    }
+
+    const buffer = Buffer.from(await res.arrayBuffer());
+    if (!buffer.length || buffer.length > MAX_REMOTE_MEDIA_BYTES) return null;
+
+    const headerMime = res.headers.get("content-type")?.split(";")[0]?.trim().toLowerCase();
+    const extMime = guessMimeType(url);
+    const mimeType =
+      headerMime && headerMime !== "application/octet-stream"
+        ? headerMime
+        : extMime !== "application/octet-stream"
+          ? extMime
+          : headerMime || "application/octet-stream";
+
+    return { buffer, mimeType };
+  } catch {
+    return null;
+  } finally {
+    clearTimeout(timer);
+  }
+}

package/src/session-usage-store.ts

@@ -0,0 +1,42 @@
+/**
+ * Reads the cumulative session-usage snapshot from the OpenClaw session store
+ * (`sessions.json`) for a given Friday session key.
+ *
+ * Shared by two readers:
+ *   - the live terminal-lifecycle forward (`friday-session.ts`), which stamps the
+ *     snapshot onto the `lifecycle.end` frame, and
+ *   - the history endpoint (`http/handlers/history-messages.ts`), which returns it
+ *     alongside the transcript so a rebuild can restore the nav-bar context ring.
+ *
+ * The snapshot is **session-cumulative**, not per-message: `context.windowMax` is
+ * the model's context window and `context.used` is the running session total. The
+ * transcript only carries per-message `model` + `usage.{total,input,output}`; the
+ * context-window figures live only here, in the session store.
+ */
+
+import { getFridayAgentForwardRuntime } from "./agent-forward-runtime.js";
+import { toSessionStoreKey, agentIdFromSessionKey } from "./session/session-manager.js";
+import { buildSessionUsageSnapshot } from "./session-usage-snapshot.js";
+import type { FridaySessionUsagePayload } from "./session-usage-snapshot.js";
+
+export function readSessionUsageSnapshotFromStore(
+  sessionKeyForStore: string,
+): FridaySessionUsagePayload | undefined {
+  const access = getFridayAgentForwardRuntime();
+  if (!access) return undefined;
+  try {
+    const cfg = access.getConfig() as { session?: { store?: string } } | null | undefined;
+    const storeConfig = cfg?.session?.store;
+    const canonical = toSessionStoreKey(sessionKeyForStore);
+    const storePath = access.resolveStorePath(storeConfig, { agentId: agentIdFromSessionKey(canonical) });
+    const store = access.loadSessionStore(storePath, { skipCache: true }) as Record<
+      string,
+      Record<string, unknown>
+    >;
+    const entry = store[canonical] ?? store[sessionKeyForStore.trim()];
+    if (!entry || typeof entry !== "object") return undefined;
+    return buildSessionUsageSnapshot(entry);
+  } catch {
+    return undefined;
+  }
+}