@saadnvd1/agent-os 0.3.464 → 0.3.465

package/README.md

@@ -311,6 +311,19 @@ mode and starts it, **Keep planning** goes back to the composer.
 The ring in the tab bar (in the composer on a phone) is how full the
 conversation's context is, measured against the room before auto-compact:
 amber past 60%, red past 85%. Tap it for the breakdown and **Compact now**.
+
+A message to a chat idle past its prompt cache (5 minutes or an hour, read
+from the agent's own usage) re-reads the whole conversation at the
+cache-write price. When the context is also above a threshold (150k tokens by
+default, Settings → Workspaces → Compact idle chats; off sets it to never), a
+chip above the composer says "Idle 47m · 412k context · Compact first?": Send
+compacts and then sends, **Send as-is** skips it for that one message.
+Messages nobody is typing (the orchestrator's `send`, AgentOS events and
+wakes, `aos send`, schedules) compact first on their own, only between turns,
+and the chat shows one quiet line with the context before and after. An
+orchestrator isn't compacted (a summary would lose the fence around what it
+read from tasks and CI): it starts a fresh conversation from its brief and
+the current state instead, as at its fresh-start threshold.
 On a desktop browser the screen button attaches a screenshot of a screen or
 window you pick; on a phone, attach a screenshot as a photo.
 

package/app/api/fresh-start/route.ts

@@ -2,15 +2,17 @@ import { NextRequest, NextResponse } from "next/server";
 import { refreshSettings, setRefreshSettings } from "@/lib/chat/refresh";
 
 // When a chat's conversation starts over (lib/chat/refresh): context
-// tokens for orchestrators and for tasks, 0 for never.
+// tokens for orchestrators and for tasks, and above which a stale chat is
+// compacted before a message (lib/chat/stale); 0 for never.
 export async function GET() {
   return NextResponse.json(refreshSettings());
 }
 
 export async function PUT(request: NextRequest) {
   try {
-    const { orchestratorTokens, taskTokens } = await request.json();
-    setRefreshSettings({ orchestratorTokens, taskTokens });
+    const { orchestratorTokens, taskTokens, staleCompactTokens } =
+      await request.json();
+    setRefreshSettings({ orchestratorTokens, taskTokens, staleCompactTokens });
     return NextResponse.json(refreshSettings());
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);

package/components/Chat/ChatPanel.tsx

@@ -26,6 +26,9 @@ import { SubagentCard } from "./Subagent";
 import { UndoDialog, UndoneBlock } from "./Undo";
 import { Composer } from "./Composer";
 import { Queue } from "./Queue";
+import { StaleChip } from "./StaleChip";
+import { composerCompacts } from "@/lib/chat/stale";
+import { useFreshStartQuery } from "@/data/fresh-start";
 import { QuoteButton } from "./QuoteButton";
 import { ToolBodies, ToolGroup } from "./Tools";
 import { RowState, RowStore } from "./rowState";
@@ -282,6 +285,12 @@ export function ChatPanel({
     toEnd();
     send(text);
   };
+  // A stale chat compacts before the next message unless the reader picks
+  // "Send as-is", for that send only.
+  const staleCompactTokens = useFreshStartQuery().data?.staleCompactTokens ?? 0;
+  const [asIsFor, setAsIsFor] = useState<string | null>(null);
+  const asIs = asIsFor === sessionId;
+  const setAsIs = (on: boolean) => setAsIsFor(on ? sessionId : null);
 
   // Shift+Tab switches plan mode from the composer, as in the terminal.
   const shiftTab = useRef(togglePlan);
@@ -517,6 +526,13 @@ export function ChatPanel({
             )
           }
         />
+        <StaleChip
+          context={context}
+          state={state}
+          thresholdTokens={staleCompactTokens}
+          asIs={asIs}
+          onAsIs={setAsIs}
+        />
         <Composer
           draftKey={sessionId}
           suggestion={shownSuggestion}
@@ -529,7 +545,13 @@ export function ChatPanel({
           placeholder={connected ? `Message ${sessionName}` : "Reconnecting…"}
           onSend={(text, images) => {
             toEnd();
-            send(text, images.length ? images : undefined);
+            const compact = composerCompacts(text, context, {
+              state,
+              thresholdTokens: staleCompactTokens,
+              asIs,
+            });
+            setAsIs(false);
+            send(text, images.length ? images : undefined, compact);
           }}
           onStop={interrupt}
           commands={commands}

package/components/Chat/Messages.tsx

@@ -4,6 +4,7 @@ import { Check, ChevronRight, Circle, CircleDot, Sparkles } from "lucide-react";
 import type { ChatItem } from "@/lib/chat/events";
 import { cn } from "@/lib/utils";
 import { leadingCommand } from "@/lib/chat/commands";
+import { compactedLine } from "@/lib/chat/stale";
 import { CopyButton } from "./CopyButton";
 import { ImageThumb } from "./ImageThumb";
 import { Markdown } from "./Markdown";
@@ -184,9 +185,7 @@ export function Compacted({ item }: { item: Of<"compacted"> }) {
   return (
     <div className="text-muted-foreground/60 flex items-center gap-3 font-mono text-[11px]">
       <span className="bg-foreground/[0.06] h-px flex-1" />
-      {item.trigger === "auto"
-        ? "Context compacted automatically"
-        : "Context compacted"}
+      {compactedLine(item)}
       <span className="bg-foreground/[0.06] h-px flex-1" />
     </div>
   );

package/components/Chat/StaleChip.tsx

@@ -0,0 +1,55 @@
+"use client";
+
+import { Minimize2 } from "lucide-react";
+import type { ChatContext, ChatState } from "@/lib/chat/events";
+import { staleLabel, staleness } from "@/lib/chat/stale";
+import { cn } from "@/lib/utils";
+import { useNow } from "./useNow";
+
+// Above the composer while the chat is stale (lib/chat/stale): its prompt
+// cache has expired and its context is long, so the next message would
+// re-read all of it at full price. Send compacts first unless the reader
+// picks "Send as-is", for that one send only.
+export function StaleChip({
+  context,
+  state,
+  thresholdTokens,
+  asIs,
+  onAsIs,
+}: {
+  context: ChatContext | null;
+  state: ChatState;
+  thresholdTokens: number;
+  asIs: boolean;
+  onAsIs: (asIs: boolean) => void;
+}) {
+  const watching = !!context?.cacheTtlMs && thresholdTokens > 0;
+  const now = useNow(watching);
+  const stale = staleness(context, { state, thresholdTokens, now });
+  if (!stale) return null;
+  return (
+    <div
+      role="status"
+      className="bg-card popover-surface mb-2 flex items-center gap-2 rounded-2xl py-1 pr-1 pl-3 text-xs"
+    >
+      <Minimize2 className="text-muted-foreground h-3.5 w-3.5 shrink-0" />
+      <span className="text-muted-foreground min-w-0 flex-1 truncate">
+        {staleLabel(stale)} ·{" "}
+        <span className="text-foreground">
+          {asIs ? "Sending as-is" : "Compact first?"}
+        </span>
+      </span>
+      <button
+        type="button"
+        aria-pressed={asIs}
+        onClick={() => onAsIs(!asIs)}
+        className={cn(
+          "hover:bg-foreground/[0.06] min-h-11 shrink-0 rounded-xl px-3 font-medium md:min-h-8",
+          asIs && "text-primary"
+        )}
+      >
+        {asIs ? "Compact first" : "Send as-is"}
+      </button>
+    </div>
+  );
+}

package/components/Workspaces/FreshStartForm.tsx

@@ -18,7 +18,10 @@ export function FreshStartForm() {
   if (isError)
     return <p className="text-destructive text-sm">{error.message}</p>;
   return (
-    <Form key={`${data.orchestratorTokens}:${data.taskTokens}`} saved={data} />
+    <Form
+      key={`${data.orchestratorTokens}:${data.taskTokens}:${data.staleCompactTokens}`}
+      saved={data}
+    />
   );
 }
 
@@ -26,11 +29,13 @@ function Form({ saved }: { saved: RefreshSettings }) {
   const update = useUpdateFreshStart();
   const orchestrator = useThreshold(saved.orchestratorTokens, 200);
   const task = useThreshold(saved.taskTokens, 200);
-  const error = orchestrator.error ?? task.error;
+  const stale = useThreshold(saved.staleCompactTokens, 150);
+  const error = orchestrator.error ?? task.error ?? stale.error;
   const dirty =
     !error &&
     (orchestrator.tokens !== saved.orchestratorTokens ||
-      task.tokens !== saved.taskTokens);
+      task.tokens !== saved.taskTokens ||
+      stale.tokens !== saved.staleCompactTokens);
 
   return (
     <form
@@ -38,9 +43,13 @@ function Form({ saved }: { saved: RefreshSettings }) {
         e.preventDefault();
         if (error) return;
         update.mutate(
-          { orchestratorTokens: orchestrator.tokens, taskTokens: task.tokens },
           {
-            onSuccess: () => toast.success("Fresh starts saved"),
+            orchestratorTokens: orchestrator.tokens,
+            taskTokens: task.tokens,
+            staleCompactTokens: stale.tokens,
+          },
+          {
+            onSuccess: () => toast.success("Context settings saved"),
             onError: (err) => toast.error(err.message),
           }
         );
@@ -56,6 +65,18 @@ function Form({ saved }: { saved: RefreshSettings }) {
       </p>
       <ThresholdRow label="Orchestrators" field={orchestrator} />
       <ThresholdRow label="Tasks" field={task} />
+      <h3 className="pt-2 text-sm font-medium">Compact idle chats</h3>
+      <p className="text-muted-foreground text-sm">
+        A message to a chat idle past its prompt cache re-reads the whole
+        conversation at full price. Above this size, messages from the
+        orchestrator, events and schedules compact it first; the composer offers
+        to.
+      </p>
+      <ThresholdRow
+        label="Idle chats"
+        field={stale}
+        switchLabel="Compact idle chats before a message"
+      />
       {error && <p className="text-destructive text-xs">{error}</p>}
       <div className="flex justify-end">
         <Button
@@ -90,9 +111,11 @@ function useThreshold(tokens: number, fallbackK: number) {
 function ThresholdRow({
   label,
   field,
+  switchLabel,
 }: {
   label: string;
   field: ReturnType<typeof useThreshold>;
+  switchLabel?: string;
 }) {
   return (
     <div className="space-y-2">
@@ -101,7 +124,7 @@ function ThresholdRow({
         <Switch
           checked={field.on}
           onCheckedChange={field.setOn}
-          aria-label={`Fresh starts for ${label.toLowerCase()}`}
+          aria-label={switchLabel ?? `Fresh starts for ${label.toLowerCase()}`}
         />
       </label>
       {field.on && (

package/data/chat/useChat.ts

@@ -298,10 +298,18 @@ export function useChat(
 
   const queryClient = useQueryClient();
   const send = useCallback(
-    (text: string, images?: ChatImage[]) => {
+    // `compact`: the reader let a stale chat compact first (lib/chat/stale).
+    (text: string, images?: ChatImage[], compact?: boolean) => {
       const ws = wsRef.current;
       if (!ws) return;
-      ws.send(JSON.stringify({ type: "send", text, images }));
+      ws.send(
+        JSON.stringify({
+          type: "send",
+          text,
+          images,
+          ...(compact && { compact: true }),
+        })
+      );
       if (ws.readyState === WebSocket.OPEN) markRunning(queryClient, sessionId);
     },
     [queryClient, sessionId]

package/lib/bus/index.ts

@@ -163,6 +163,9 @@ async function deliver(
         from: from.name,
         peer: from.peer,
         origin: from.origin,
+        // Nobody is at the composer to choose: a stale chat is compacted
+        // first (lib/chat/stale).
+        compact: "auto",
       });
       return { state };
     } catch (error) {

package/lib/chat/client-send.ts

@@ -1,14 +1,22 @@
 import type { ChatImage } from "./events";
+import type { CompactFirst } from "./stale";
 
-// What a browser's send may carry: its text and images. Who a message is
-// from (`from`, `peer`, `origin`) is set by the server alone, never by a client.
+// What a browser's send may carry: its text and images, and whether the
+// reader chose to compact a stale chat first. Who a message is from (`from`,
+// `peer`, `origin`) is set by the server alone, never by a client.
 export function clientSend(msg: unknown): {
   text: string;
   images?: ChatImage[];
+  compact?: CompactFirst;
 } {
-  const m = (msg ?? {}) as { text?: unknown; images?: unknown };
+  const m = (msg ?? {}) as {
+    text?: unknown;
+    images?: unknown;
+    compact?: unknown;
+  };
   return {
     text: typeof m.text === "string" ? m.text : "",
     images: Array.isArray(m.images) ? (m.images as ChatImage[]) : undefined,
+    ...(m.compact === true && { compact: "yes" as const }),
   };
 }

package/lib/chat/drivers/claude-mapper.ts

@@ -31,6 +31,10 @@ export type ClaudeMessage = {
       input_tokens?: number;
       output_tokens?: number;
       cache_creation_input_tokens?: number;
+      cache_creation?: {
+        ephemeral_5m_input_tokens?: number;
+        ephemeral_1h_input_tokens?: number;
+      } | null;
     };
   };
   event?: {
@@ -49,7 +53,11 @@ export type ClaudeMessage = {
   content?: string;
   terminal_slash_commands?: string[];
   commands?: SdkCommand[];
-  compact_metadata?: { trigger?: "manual" | "auto" };
+  compact_metadata?: {
+    trigger?: "manual" | "auto";
+    pre_tokens?: number;
+    post_tokens?: number;
+  };
   // Background tasks (task_started, task_progress, task_notification).
   task_id?: string;
   tool_use_id?: string;
@@ -223,6 +231,8 @@ export class ClaudeMapper {
               id: randomUUID(),
               kind: "compacted",
               trigger: m.compact_metadata?.trigger,
+              before: m.compact_metadata?.pre_tokens,
+              after: m.compact_metadata?.post_tokens,
               createdAt: now(),
             },
           },

package/lib/chat/drivers/claude.ts

@@ -10,6 +10,7 @@ import type { DriverEvent, FileSuggestion, McpServerView } from "../events";
 import { InputQueue } from "../queue";
 import { Approvals, isPlanFile, sdkMode } from "./claude-approvals";
 import { toChatContext, usageTotals } from "../context";
+import { cacheTtlMs } from "../stale";
 import { ClaudeMapper, toCommand, type ClaudeMessage } from "./claude-mapper";
 import { SuggestionTrace } from "./suggestion-trace";
 import { redact } from "../../orchestrator/untrusted";
@@ -224,6 +225,8 @@ export const claudeDriver: ChatDriver = {
       () => plan
     );
     let sessionId = options.resumeId ?? null;
+    // The prompt-cache lifetime its turns write with (lib/chat/stale).
+    let cacheTtl: number | undefined;
 
     // What the agent restored on starting: a resumed conversation's totals
     // when its last process saved them, nothing otherwise. Each turn's cost
@@ -248,13 +251,18 @@ export const claudeDriver: ChatDriver = {
           planFile = writtenPlanFile(m) ?? planFile;
           trace.message(m);
           for (const e of mapper.map(m)) out.push(e);
+          if (m.type === "assistant" && !m.parent_tool_use_id)
+            cacheTtl = cacheTtlMs(m.message?.usage?.cache_creation) ?? cacheTtl;
           // How full the window is now, for the meter, without holding up
           // the conversation.
           if (m.type === "result")
             void q
               .getContextUsage({ detail: "summary" })
               .then((u) =>
-                out.push({ type: "context", context: toChatContext(u) })
+                out.push({
+                  type: "context",
+                  context: { ...toChatContext(u), cacheTtlMs: cacheTtl },
+                })
               )
               .catch(() => {});
         }

package/lib/chat/events.ts

@@ -106,7 +106,11 @@ export interface ChatContext {
   percentage: number;
   categories: { name: string; tokens: number }[];
   model?: string;
+  // When it was measured: the end of the last turn.
   at: number;
+  // The prompt-cache lifetime the conversation writes with (lib/chat/stale),
+  // once a turn has said.
+  cacheTtlMs?: number;
 }
 
 // Running totals the agent reports at the end of each turn.
@@ -174,7 +178,16 @@ export type ChatItem =
   | (Base & { kind: "command_output"; text: string })
   // The conversation's MCP servers, as /mcp reports them.
   | (Base & { kind: "mcp"; servers: McpServerView[] })
-  | (Base & { kind: "compacted"; trigger?: "manual" | "auto" })
+  | (Base & {
+      kind: "compacted";
+      trigger?: "manual" | "auto";
+      // Context tokens before and after, when the agent reports them.
+      before?: number;
+      after?: number;
+      // Compacted ahead of a message to a stale chat (lib/chat/stale): how
+      // long it had been idle.
+      idleMs?: number;
+    })
   // A plan the agent proposed from plan mode, and whether it was carried out.
   | (Base & { kind: "plan"; plan: string; carried?: boolean })
   | (Base & { kind: "error"; message: string })

package/lib/chat/refresh.ts

@@ -6,7 +6,8 @@
  * default: its state is in the database and its brief carries it
  * (lib/orchestrator/digest). A task keeps its progress only in its
  * conversation and its branch, so for tasks it's off unless switched on.
- * App-wide, in Settings → Workspaces.
+ * App-wide, in Settings → Workspaces, with the size past which an idle
+ * chat is compacted before a message goes in (lib/chat/stale).
  */
 
 import { db } from "../db";
@@ -14,13 +15,18 @@ import { MAX_REFRESH_TOKENS, MIN_REFRESH_TOKENS } from "./refresh-limits";
 
 export const ORCHESTRATOR_KEY = "orchestrator.refresh_tokens";
 export const TASK_KEY = "chat.task_refresh_tokens";
+export const STALE_COMPACT_KEY = "chat.stale_compact_tokens";
 export const DEFAULT_ORCHESTRATOR_TOKENS = 200_000;
+export const DEFAULT_STALE_COMPACT_TOKENS = 150_000;
 export { MIN_REFRESH_TOKENS, MAX_REFRESH_TOKENS } from "./refresh-limits";
 
 export interface RefreshSettings {
   // Context tokens at which a conversation starts over; 0 is off.
   orchestratorTokens: number;
   taskTokens: number;
+  // Context tokens above which a chat whose prompt cache has expired is
+  // compacted before the next message; 0 is off.
+  staleCompactTokens: number;
 }
 
 function read(key: string, fallback: number): number {
@@ -35,6 +41,7 @@ export function refreshSettings(): RefreshSettings {
   return {
     orchestratorTokens: read(ORCHESTRATOR_KEY, DEFAULT_ORCHESTRATOR_TOKENS),
     taskTokens: read(TASK_KEY, 0),
+    staleCompactTokens: read(STALE_COMPACT_KEY, DEFAULT_STALE_COMPACT_TOKENS),
   };
 }
 
@@ -49,7 +56,7 @@ export function checkRefreshTokens(value: unknown): number {
     value > MAX_REFRESH_TOKENS
   )
     throw new Error(
-      `A fresh-start threshold is off or between ${MIN_REFRESH_TOKENS / 1000}k and ${MAX_REFRESH_TOKENS / 1000}k tokens`
+      `A context threshold is off or between ${MIN_REFRESH_TOKENS / 1000}k and ${MAX_REFRESH_TOKENS / 1000}k tokens`
     );
   return value;
 }
@@ -67,6 +74,11 @@ export function setRefreshSettings(input: Partial<RefreshSettings>): void {
     ]);
   if (input.taskTokens !== undefined)
     checked.push([TASK_KEY, checkRefreshTokens(input.taskTokens)]);
+  if (input.staleCompactTokens !== undefined)
+    checked.push([
+      STALE_COMPACT_KEY,
+      checkRefreshTokens(input.staleCompactTokens),
+    ]);
   db.transaction(() => {
     for (const [key, n] of checked) put.run(key, String(n));
   })();

package/lib/chat/runner.ts

@@ -8,6 +8,7 @@
 import { randomUUID } from "crypto";
 import os from "os";
 import { db, type Session } from "../db";
+import type { CompactFirst } from "./stale";
 import type {
   ApprovalDecision,
   ChatContext,
@@ -329,6 +330,8 @@ export async function sendChat(
     images?: ChatImage[];
     // Typed in the composer: waits in the queue while a turn runs.
     queue?: boolean;
+    // Compact a stale chat first (lib/chat/stale).
+    compact?: CompactFirst;
   } & SentBy
 ): Promise<void> {
   const text = input.text.trim();
@@ -356,6 +359,7 @@ export async function sendChat(
     images: input.images,
     ...sentBy(input),
     queue: input.queue,
+    compact: input.compact,
   });
 }
 
@@ -486,6 +490,8 @@ async function resumeCutOff(sessionId: string): Promise<void> {
       text: RESUME_NOTE,
       from: "agentos",
       origin: { kind: "event", label: "AgentOS" },
+      // Down past its cache, a long chat is compacted before it carries on.
+      compact: "auto",
     });
     if (task)
       queueEvent(
@@ -552,7 +558,7 @@ export async function chatFileSuggestions(
 // only then has it accepted it. "queued" when a turn was already running.
 export async function sendChatConfirmed(
   sessionId: string,
-  input: { text: string; id?: string } & SentBy,
+  input: { text: string; id?: string; compact?: CompactFirst } & SentBy,
   timeoutMs = 10_000
 ): Promise<"delivered" | "queued"> {
   const text = input.text.trim();
@@ -607,6 +613,7 @@ export async function sendChatConfirmed(
       id,
       text,
       ...sentBy(input),
+      compact: input.compact,
     });
     await accepted;
   } finally {

package/lib/chat/stale.ts

@@ -0,0 +1,95 @@
+/**
+ * Stale chats: a message sent to a conversation whose prompt cache has
+ * expired re-reads the whole history at the cache-write price. When it is
+ * also long, compacting first is far cheaper than carrying it (one summary
+ * turn, then a small cache write instead of a huge one). The one check every
+ * send path uses: the composer to offer it (components/Chat/StaleChip), the
+ * chat worker to do it for automated sends (lib/chat/worker/host).
+ *
+ * Pure, so the browser and the worker read the same rule.
+ */
+
+import type { ChatContext, ChatItem, ChatState } from "./events";
+import { formatTokens } from "./context";
+
+// How a send treats a stale chat: "auto" compacts first only when it is
+// stale (automated sends); "yes" compacts first because the reader chose
+// to (the composer's chip). Absent, it never does.
+export type CompactFirst = "auto" | "yes";
+
+// The prompt-cache lifetime a turn wrote with, read from its usage: the
+// session runs with one or the other, and only a write says which. A turn
+// that only read the cache says nothing.
+export function cacheTtlMs(
+  cacheCreation:
+    | {
+        ephemeral_5m_input_tokens?: number;
+        ephemeral_1h_input_tokens?: number;
+      }
+    | null
+    | undefined
+): number | undefined {
+  if (!cacheCreation) return undefined;
+  if ((cacheCreation.ephemeral_1h_input_tokens ?? 0) > 0) return 60 * 60_000;
+  if ((cacheCreation.ephemeral_5m_input_tokens ?? 0) > 0) return 5 * 60_000;
+  return undefined;
+}
+
+export interface Staleness {
+  idleMs: number;
+  tokens: number;
+}
+
+// Stale: no turn running, the last one ended longer ago than the cache it
+// wrote lives, and the context is above the threshold (0 is off). Null when
+// it isn't, or when the chat never said which cache it uses.
+export function staleness(
+  context: ChatContext | null | undefined,
+  opts: { state: ChatState; thresholdTokens: number; now?: number }
+): Staleness | null {
+  if (opts.state === "running" || opts.state === "waiting") return null;
+  if (!context?.cacheTtlMs || opts.thresholdTokens <= 0) return null;
+  const idleMs = (opts.now ?? Date.now()) - context.at;
+  if (idleMs <= context.cacheTtlMs) return null;
+  if (context.usedTokens <= opts.thresholdTokens) return null;
+  return { idleMs, tokens: context.usedTokens };
+}
+
+export function formatIdle(ms: number): string {
+  const m = Math.floor(ms / 60_000);
+  if (m < 120) return `${m}m`;
+  const h = Math.floor(m / 60);
+  return h < 48 ? `${h}h` : `${Math.floor(h / 24)}d`;
+}
+
+// "Idle 47m · 412k context"
+export function staleLabel(s: Staleness): string {
+  return `Idle ${formatIdle(s.idleMs)} · ${formatTokens(s.tokens)} context`;
+}
+
+// Whether the composer's send compacts first: the chip was showing and the
+// reader didn't pick "Send as-is". A slash command goes as typed.
+export function composerCompacts(
+  text: string,
+  context: ChatContext | null | undefined,
+  opts: { state: ChatState; thresholdTokens: number; asIs: boolean }
+): boolean {
+  if (opts.asIs || text.trimStart().startsWith("/")) return false;
+  return !!staleness(context, opts);
+}
+
+// The chat's line for a compaction: "Compacted before sending · idle 47m ·
+// 412k → 38k tokens" when it ran ahead of a message to a stale chat.
+export function compactedLine(
+  item: Extract<ChatItem, { kind: "compacted" }>
+): string {
+  const head =
+    item.idleMs !== undefined
+      ? `Compacted before sending · idle ${formatIdle(item.idleMs)}`
+      : item.trigger === "auto"
+        ? "Context compacted automatically"
+        : "Context compacted";
+  if (item.before === undefined) return head;
+  const after = item.after === undefined ? "…" : formatTokens(item.after);
+  return `${head} · ${formatTokens(item.before)} → ${after} tokens`;
+}

package/lib/chat/worker/host.ts

@@ -13,6 +13,7 @@ import { resolveModelForAgent } from "../../model-catalog";
 import { chatDriverFor } from "../drivers";
 import type { ChatConversation } from "../driver";
 import type {
+  ChatContext,
   ChatImage,
   ChatItem,
   ChatState,
@@ -35,7 +36,8 @@ import {
   visualsTools,
 } from "../../artifacts/tools";
 import type { RoleExtras } from "./extras";
-import { refreshedNote } from "../refresh";
+import { refreshSettings, refreshedNote } from "../refresh";
+import { staleLabel, staleness, type Staleness } from "../stale";
 import type { WorkerCommand, WorkerEvent } from "./protocol";
 
 // How soon after a stopped turn ends a turn the agent starts on its own
@@ -123,6 +125,19 @@ export class ChatHost {
   // size can't end every conversation after one turn.
   private freshConversation: boolean;
   private contextBase: number | null = null;
+  // How full the conversation was at its last turn's end (lib/chat/stale).
+  private context: ChatContext | null = null;
+  // A compaction run ahead of a message to a stale chat: the message waits
+  // at the front of the queue until it ends (compactFirst).
+  private compacting: {
+    idleMs: number;
+    before: number;
+    done?: boolean;
+  } | null = null;
+  // Its line, until the agent's next measure gives the size after.
+  private compactedLine: Extract<ChatItem, { kind: "compacted" }> | null = null;
+  // An orchestrator gone stale starts over rather than compacting.
+  private staleRefresh: Staleness | null = null;
   readonly done: Promise<void>;
 
   constructor(
@@ -182,11 +197,19 @@ export class ChatHost {
       permissionMode: extras.permissionMode,
     });
     this.suggestion = session.chat_suggestion ?? null;
+    try {
+      this.context = session.chat_context
+        ? (JSON.parse(session.chat_context) as ChatContext)
+        : null;
+    } catch {
+      this.context = null;
+    }
     this.refresh = extras.refresh;
     this.freshConversation = !session.claude_session_id;
     if (session.chat_refreshed)
       this.refreshedNote = refreshedNote(
-        extras.refresh?.role ?? "task",
+        extras.refresh?.role ??
+          (session.role === "orchestrator" ? "orchestrator" : "task"),
         session.chat_refreshed
       );
     // Told only an orchestrator whose tools changed since its last worker:
@@ -222,6 +245,12 @@ export class ChatHost {
     try {
       for await (const e of this.conversation.events) {
         if (e.type === "item") {
+          // A compaction run for a stale chat shows as its one line; what
+          // a failed one printed still shows.
+          if (this.compacting?.done && e.item.kind === "command_output")
+            continue;
+          if (this.compacting && e.item.kind === "compacted")
+            e.item = this.compactedItem(e.item);
           if ("streaming" in e.item && e.item.streaming)
             this.streaming.set(e.item.id, e.item);
           else this.streaming.delete(e.item.id);
@@ -259,7 +288,9 @@ export class ChatHost {
             JSON.stringify(e.context),
             this.session.id
           );
+          this.context = e.context;
           this.emit(e);
+          this.settleCompactedLine(e.context.usedTokens);
           this.refreshIfFull(e.context.usedTokens);
         } else if (e.type === "turn_start") {
           this.turnsStarted++;
@@ -303,6 +334,8 @@ export class ChatHost {
             // A send waiting on the same change may have started a turn
             // meanwhile: that turn is running, not idle.
             if (this.busy()) continue;
+            // The compaction ran (or failed): its message is first in line.
+            this.compacting = null;
             if (this.sendQueued()) continue;
           }
           // A stopped turn can still settle an approval after it ended.
@@ -503,7 +536,13 @@ export class ChatHost {
           this.sendUser(cmd, true);
           return;
         }
-        if (cmd.queue && (this.busy() || listQueue(this.session.id).length)) {
+        if (this.compactFirst(cmd)) return;
+        // A compaction run for an earlier message takes nothing in: what's
+        // sent meanwhile goes behind that message.
+        if (
+          (cmd.queue || this.compacting) &&
+          (this.busy() || listQueue(this.session.id).length)
+        ) {
           // Behind the running turn, and behind anything queued before it.
           enqueue(this.session.id, cmd);
           this.emit({ type: "queue" });
@@ -620,6 +659,88 @@ export class ChatHost {
     this.close();
   }
 
+  // A stale chat (lib/chat/stale) is compacted before the message goes in,
+  // only between turns: the message waits at the front of the queue, and
+  // the compaction's end sends it. "yes" is the reader's choice, made on
+  // what the composer showed; "auto" checks for itself.
+  private compactFirst(cmd: Extract<WorkerCommand, { type: "send" }>): boolean {
+    if (!cmd.compact || this.busy() || this.closed || this.handingOver())
+      return false;
+    const stale = this.staleNow(cmd.compact);
+    if (!stale) return false;
+    try {
+      enqueue(this.session.id, cmd);
+    } catch {
+      // A full queue: it goes in as it is.
+      return false;
+    }
+    moveToFront(this.session.id, cmd.id);
+    this.emit({ type: "queue" });
+    // An orchestrator isn't compacted: a summary would carry what it read
+    // from tasks and CI without its untrusted fence. It starts a fresh
+    // conversation from its brief and the database instead, as at its
+    // threshold, and the next worker sends the message.
+    if (this.session.role === "orchestrator") {
+      this.staleRefresh = stale;
+      this.refreshAt = stale.tokens;
+      this.retiring = true;
+      this.retireWaited = true;
+      this.retireIfDone();
+      return true;
+    }
+    this.compacting = { idleMs: stale.idleMs, before: stale.tokens };
+    this.currentTurn = null;
+    this.stopping = null;
+    this.conversation.send("/compact");
+    this.setState("running");
+    console.error(
+      `${new Date().toISOString()} compacting ${this.session.id} before a message: idle ${Math.round(stale.idleMs / 60_000)}m, ${stale.tokens} tokens`
+    );
+    return true;
+  }
+
+  private staleNow(compact: "auto" | "yes"): Staleness | null {
+    const context = this.context;
+    // Only an agent that says which cache it uses has one to lose.
+    if (!context?.cacheTtlMs) return null;
+    if (compact === "yes")
+      return { idleMs: Date.now() - context.at, tokens: context.usedTokens };
+    return staleness(context, {
+      state: this.state,
+      thresholdTokens: refreshSettings().staleCompactTokens,
+    });
+  }
+
+  private compactedItem(
+    item: Extract<ChatItem, { kind: "compacted" }>
+  ): ChatItem {
+    if (this.compacting) this.compacting.done = true;
+    const line = {
+      ...item,
+      idleMs: this.compacting?.idleMs,
+      before: item.before ?? this.compacting?.before,
+    };
+    this.compactedLine = line.after === undefined ? line : null;
+    if (line.after !== undefined) this.logCompacted(line);
+    return line;
+  }
+
+  // The size after, from the measure that follows the compaction's result.
+  private settleCompactedLine(usedTokens: number): void {
+    const line = this.compactedLine;
+    if (!line) return;
+    this.compactedLine = null;
+    const settled = { ...line, after: usedTokens };
+    this.record(settled);
+    this.logCompacted(settled);
+  }
+
+  private logCompacted(line: { before?: number; after?: number }): void {
+    console.error(
+      `${new Date().toISOString()} compacted ${this.session.id}: ${line.before ?? "?"} -> ${line.after ?? "?"} tokens`
+    );
+  }
+
   // Past its threshold, once: it retires at the next turn boundary, as for
   // a deploy, without waiting for the agent's guess at the next message
   // (the new conversation never saw what it guessed from).
@@ -643,13 +764,21 @@ export class ChatHost {
          chat_suggestion = NULL, chat_context = NULL, chat_restarted = 0,
          chat_refreshed = ? WHERE id = ?`
     ).run(this.refreshAt, this.session.id);
+    const brief = `its brief${this.session.role === "orchestrator" ? " and the current state from AgentOS" : ""}`;
+    const stale = this.staleRefresh;
     this.record({
       id: `note-refresh-${Date.now()}`,
       kind: "note",
       tone: "note",
-      text: `Context reached ${Math.round(this.refreshAt / 1000)}k tokens: the agent starts a fresh conversation with its brief${this.refresh?.role === "orchestrator" ? " and the current state from AgentOS" : ""} at its next message.`,
+      text: stale
+        ? `${staleLabel(stale)}, past its prompt cache: the agent starts a fresh conversation with ${brief} before the next message.`
+        : `Context reached ${Math.round(this.refreshAt / 1000)}k tokens: the agent starts a fresh conversation with ${brief} at its next message.`,
       createdAt: Date.now(),
     });
+    if (stale)
+      console.error(
+        `${new Date().toISOString()} fresh start for stale ${this.session.id}: ${stale.tokens} tokens, idle ${Math.round(stale.idleMs / 60_000)}m`
+      );
   }
 
   // Retiring, and nothing in the background keeps it: messages wait in the

package/lib/chat/worker/protocol.ts

@@ -18,6 +18,7 @@ import type {
   PeerMessage,
 } from "../events";
 import type { UndoResult } from "../driver";
+import type { CompactFirst } from "../stale";
 
 export const PROTOCOL_VERSION = 1;
 
@@ -35,6 +36,8 @@ export type WorkerCommand =
       // From the composer: waits its turn behind a running one, in the
       // queue, rather than joining it.
       queue?: boolean;
+      // Compact a stale conversation before this goes in (lib/chat/stale).
+      compact?: CompactFirst;
     }
   // A queued message goes next: the running turn stops for it.
   // `during`: the user message whose turn the reader saw running; only that

package/lib/orchestrator/deliver.ts

@@ -1,4 +1,5 @@
 import type { ChatOrigin, ChatState } from "../chat/events";
+import type { CompactFirst } from "../chat/stale";
 import {
   isAnswer,
   deliveriesSince,
@@ -22,7 +23,12 @@ export const AGENTOS_SENDER = "agentos";
 
 export type ChatSender = (
   sessionId: string,
-  input: { text: string; from: string; origin: ChatOrigin }
+  input: {
+    text: string;
+    from: string;
+    origin: ChatOrigin;
+    compact: CompactFirst;
+  }
 ) => Promise<void>;
 
 // After a failed send, wait 5s, then 10s, 20s ... up to 5 minutes.
@@ -97,6 +103,8 @@ export async function deliverEvents(opts: {
       text,
       from: AGENTOS_SENDER,
       origin,
+      // An orchestrator idle past its cache is compacted first.
+      compact: "auto",
     });
     failing.delete(workspaceId);
     return text;

package/lib/schedules/start.ts

@@ -139,6 +139,7 @@ async function postToOrchestrator(
       ? `${fromLabel(schedule)}, set up by "${creator.name}"`
       : fromLabel(schedule),
     origin: scheduleOrigin(schedule, creator),
+    compact: "auto",
   });
   onSession(orchestrator.id);
   return orchestrator.id;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@saadnvd1/agent-os",
-  "version": "0.3.464",
+  "version": "0.3.465",
   "description": "Self-hosted web UI for managing Claude Code sessions",
   "bin": {
     "agent-os": "scripts/agent-os"