@saadnvd1/agent-os 0.3.493 → 0.3.494

package/README.md

@@ -1221,6 +1221,12 @@ it may do on its own, and the lines that always come back to you as asks.
   Nothing is lost, because its state lives in the database; its chat goes on,
   with a line where it started over. The same can be switched on for chat
   tasks (off by default: a task keeps only its brief and its branch).
+  **Start fresh by hand:** after a deploy that changes its permissions or
+  brief, use **New conversation (keep brief)** in the orchestrator's row menu or type `/fresh`
+  in its chat (task chats have both too). It takes the threshold's path: an
+  idle agent starts over at once; a running turn finishes first, with a
+  "Starts fresh after this turn" line. The next conversation launches with
+  the brief, permissions and workspace state the server has then.
 - **Events:** the server sends it one short line per event (a PR opened, CI
   failed, or green once it has settled so `sign_off`'s ci gate passes, a `BLOCKED:` line, a merge, a session needing input, a
   stack step, a task idle 30 minutes with no PR, a review's verdict). Events

package/app/api/sessions/[id]/fresh/route.ts

@@ -0,0 +1,31 @@
+import { NextResponse } from "next/server";
+import { queries, db, type Session } from "@/lib/db";
+import { FreshRefusal, freshStartChat } from "@/lib/chat/runner";
+
+// POST /api/sessions/:id/fresh - start the agent's conversation over (the
+// path the context threshold takes, lib/chat/refresh): now if it's idle,
+// else at the next turn boundary. Only for chats whose state lives outside
+// the conversation: an orchestrator, or a task with a brief.
+export async function POST(
+  _request: Request,
+  { params }: { params: Promise<{ id: string }> }
+) {
+  const { id } = await params;
+  const session = queries.getSession(db).get(id) as Session | undefined;
+  if (!session)
+    return NextResponse.json({ error: "Session not found" }, { status: 404 });
+  if (session.role !== "orchestrator" && !session.task_brief)
+    return NextResponse.json(
+      { error: "Only an orchestrator or a task can start fresh" },
+      { status: 400 }
+    );
+  try {
+    return NextResponse.json({ when: await freshStartChat(id) });
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return NextResponse.json(
+      { error: message },
+      { status: error instanceof FreshRefusal ? 409 : 500 }
+    );
+  }
+}

package/components/Chat/ChatPanel.tsx

@@ -19,6 +19,8 @@ import {
   type TimelineBlock,
 } from "@/lib/chat/group";
 import type { ApprovalDecision, ChatItem } from "@/lib/chat/events";
+import { isFreshCommand, withFresh } from "@/lib/chat/commands";
+import { useFreshStart } from "@/data/sessions";
 import {
   escapeAction,
   GHOST_SELECTOR,
@@ -206,6 +208,7 @@ export function ChatPanel({
   sessionName,
   accessLocked = false,
   orchestratorOf,
+  freshStart = false,
   active,
 }: {
   sessionId: string;
@@ -214,6 +217,8 @@ export function ChatPanel({
   accessLocked?: boolean;
   // The workspace it orchestrates: its header line, Pause and asks show on top.
   orchestratorOf?: string | null;
+  // An orchestrator or task: /fresh starts its conversation over.
+  freshStart?: boolean;
   // The tab on show in the focused pane: opening it takes the caret.
   active: boolean;
 }) {
@@ -259,6 +264,7 @@ export function ChatPanel({
     requestFiles,
     search,
   } = useChat(sessionId, (text) => setPrefill({ text, at: Date.now() }));
+  const startFresh = useFreshStart();
   const { isMobile } = useViewport();
   const scrollRef = useRef<HTMLDivElement>(null);
   const listRef = useRef<HTMLDivElement>(null);
@@ -580,6 +586,10 @@ export function ChatPanel({
           disabled={!connected}
           placeholder={connected ? `Message ${sessionName}` : "Reconnecting…"}
           onSend={(text, images) => {
+            if (freshStart && isFreshCommand(text)) {
+              startFresh.mutate(sessionId);
+              return;
+            }
             toEnd();
             const compact = composerCompacts(text, context, {
               state,
@@ -590,7 +600,7 @@ export function ChatPanel({
             send(text, images.length ? images : undefined, compact);
           }}
           onStop={interrupt}
-          commands={commands}
+          commands={freshStart ? withFresh(commands) : commands}
           onRefreshCommands={refreshCommands}
           refreshingCommands={refreshingCommands}
           models={models}

package/components/Pane/index.tsx

@@ -289,6 +289,10 @@ export const Pane = memo(function Pane({
           sessionId={chat.id}
           sessionName={chat.name}
           accessLocked={chat.role === "orchestrator"}
+          freshStart={
+            (chat.role === "orchestrator" || !!chat.task_brief) &&
+            !chat.archived_at
+          }
           orchestratorOf={
             chat.role === "orchestrator" ? chat.workspace_id : null
           }

package/components/SessionList/OrchestratorPinRow.test.ts

@@ -88,6 +88,7 @@ describe("OrchestratorPinRow", () => {
     onDelete: vi.fn(),
     onMoveToProject: vi.fn(),
     onPin: vi.fn(),
+    onFresh: vi.fn(),
   };
   const render = (over: Partial<RowContextValue> = {}, unread = false) =>
     act(async () =>

package/components/SessionList/RowContext.tsx

@@ -29,6 +29,7 @@ export interface RowContextValue {
   onDelete: (sessionId: string) => void;
   onMoveToProject: (sessionId: string, projectId: string) => void;
   onPin: (sessionId: string, pinned: boolean) => void;
+  onFresh: (sessionId: string) => void;
 }
 
 const RowContext = createContext<RowContextValue | null>(null);

package/components/SessionList/SessionRowMenu.tsx

@@ -15,6 +15,7 @@ import {
   Pencil,
   Pin,
   PinOff,
+  RotateCcw,
   Sparkles,
   Trash2,
 } from "lucide-react";
@@ -174,6 +175,15 @@ export function SessionRowMenu({
           {summarizing ? "Summarizing..." : "Fresh start"}
         </Item>
       )}
+      {(session.role === "orchestrator" || session.task_brief) &&
+        session.view === "chat" &&
+        !session.archived_at &&
+        !blocked && (
+          <Item onClick={() => ctx.onFresh(session.id)}>
+            <RotateCcw className={icon} />
+            New conversation (keep brief)
+          </Item>
+        )}
       {session.pr_url && (
         <Item onClick={() => window.open(session.pr_url!, "_blank")}>
           <GitPullRequest className={icon} />

package/components/SessionList/index.tsx

@@ -4,7 +4,7 @@ import { useLayoutEffect, useMemo, useRef, useState } from "react";
 import { Loader2 } from "lucide-react";
 import { ScrollArea } from "@/components/ui/scroll-area";
 import { useDocsWorkspace } from "@/data/lumifyhub/docs";
-import { usePinSession } from "@/data/sessions";
+import { useFreshStart, usePinSession } from "@/data/sessions";
 import { useOrchestratorsQuery } from "@/data/orchestrators";
 import { docsUiActions } from "@/stores/docsUi";
 import type { SidebarRow } from "@/lib/sidebar/shelves";
@@ -47,6 +47,7 @@ export function SessionList({
   const mutations = useSessionListMutations({ onSelectSession: onSelect });
   const bulkDelete = useBulkDelete();
   const pin = usePinSession();
+  const fresh = useFreshStart();
   const { data: orchestrators = NO_ORCHESTRATORS } = useOrchestratorsQuery();
   const [dialog, setDialog] = useState<SidebarDialog | null>(null);
   const addProject = useAddProject();
@@ -70,9 +71,23 @@ export function SessionList({
   // Rows read their handlers through the latest render, so the context only
   // changes when what rows draw does: a status push redraws the rows it
   // touched, not the whole list.
-  const latest = useRef({ orderedIds, onSelect, onOpenInTab, mutations, pin });
+  const latest = useRef({
+    orderedIds,
+    onSelect,
+    onOpenInTab,
+    mutations,
+    pin,
+    fresh,
+  });
   useLayoutEffect(() => {
-    latest.current = { orderedIds, onSelect, onOpenInTab, mutations, pin };
+    latest.current = {
+      orderedIds,
+      onSelect,
+      onOpenInTab,
+      mutations,
+      pin,
+      fresh,
+    };
   });
   const canOpenInTab = !!onOpenInTab;
   const handlers = useMemo(
@@ -92,6 +107,7 @@ export function SessionList({
         latest.current.mutations.handleMoveSessionToProject(id, projectId),
       onPin: (id: string, pinned: boolean) =>
         latest.current.pin.mutate({ id, pinned }),
+      onFresh: (id: string) => latest.current.fresh.mutate(id),
     }),
     [canOpenInTab]
   );

package/data/sessions/fresh.ts

@@ -0,0 +1,20 @@
+import { useMutation } from "@tanstack/react-query";
+import { toast } from "sonner";
+
+// Starts an orchestrator's or task's conversation over (lib/chat/refresh):
+// now when idle, else after the running turn.
+export function useFreshStart() {
+  return useMutation({
+    mutationFn: async (id: string): Promise<"now" | "after-turn"> => {
+      const res = await fetch(`/api/sessions/${id}/fresh`, { method: "POST" });
+      const body = (await res.json().catch(() => ({}))) as {
+        when?: "now" | "after-turn";
+        error?: string;
+      };
+      if (!res.ok || !body.when)
+        throw new Error(body.error ?? "Couldn't start fresh");
+      return body.when;
+    },
+    onError: (e: Error) => toast.error(e.message),
+  });
+}

package/data/sessions/index.ts

@@ -11,4 +11,5 @@ export {
   useSessionSetup,
 } from "./queries";
 export { usePinSession } from "./pin";
+export { useFreshStart } from "./fresh";
 export type { LaunchSessionInput, SessionSetup } from "./queries";

package/lib/chat/commands.ts

@@ -48,3 +48,19 @@ export function insertCommand(name: string): string {
 export function leadingCommand(text: string): string | null {
   return text.match(/^\/[\w:.-]+(?=\s|$)/)?.[0] ?? null;
 }
+
+// AgentOS's own command for an orchestrator or task: starts the agent's
+// conversation over, with today's brief and permissions.
+export const FRESH_COMMAND: ChatCommand = {
+  name: "fresh",
+  description: "Start a fresh conversation with the current brief",
+};
+
+export const isFreshCommand = (text: string): boolean =>
+  text.trim().toLowerCase() === "/fresh";
+
+export function withFresh(commands: ChatCommand[]): ChatCommand[] {
+  return commands.some((c) => c.name === "fresh")
+    ? commands
+    : [FRESH_COMMAND, ...commands];
+}

package/lib/chat/refresh.ts

@@ -143,8 +143,26 @@ export function autoCompactEnv(sessionId: string): Record<string, string> {
 
 const k = (tokens: number) => `${Math.round(tokens / 1000)}k`;
 
+// Recorded as the size a conversation ended at when the reader asked for it.
+export const REQUESTED_FRESH = -1;
+
+// The agent's conversation is let go in the database: the next worker
+// starts a new one with the brief and the permissions the server has then.
+// `tokens` is the size it ended at, or REQUESTED_FRESH.
+export function releaseConversation(sessionId: string, tokens: number): void {
+  db.prepare(
+    `UPDATE sessions SET claude_session_id = NULL, chat_resume_at = NULL,
+       chat_suggestion = NULL, chat_context = NULL, chat_restarted = 0,
+       chat_refreshed = ? WHERE id = ?`
+  ).run(tokens, sessionId);
+}
+
 // What the agent reads ahead of its first message in the new conversation.
 export function refreshedNote(role: "orchestrator" | "task", tokens: number) {
+  if (tokens === REQUESTED_FRESH)
+    return role === "orchestrator"
+      ? `(AgentOS started you on a fresh conversation at the user's request. Your brief and "Where things stand" are current; carry on from them.)`
+      : `(AgentOS started you on a fresh conversation at the user's request. Your brief is above; check git status, git log and your PR to see how far you got, then carry on.)`;
   return role === "orchestrator"
     ? `(AgentOS started you on a fresh conversation: the last one passed ${k(tokens)} tokens of context. Your brief and "Where things stand" are current; carry on from them.)`
     : `(AgentOS started you on a fresh conversation: the last one passed ${k(tokens)} tokens of context. Your brief is above; check git status, git log and your PR to see how far you got, then carry on.)`;

package/lib/chat/registry.ts

@@ -24,6 +24,8 @@ export interface Live {
   // Whether it keeps the composer's queue and answers @mention lookups
   // (send_now, drain, files); an older worker drops those silently.
   canQueue?: boolean;
+  // Whether it takes "fresh" (a fresh start the reader asked for).
+  canFresh?: boolean;
   // From an older build and idle: retired once its guess at the next
   // message is in, or this fires.
   retiring?: NodeJS.Timeout;

package/lib/chat/runner.ts

@@ -50,6 +50,7 @@ import {
   queuedSessions,
 } from "./queued";
 import { fallbackFileSuggestions } from "./files";
+import { REQUESTED_FRESH, releaseConversation } from "./refresh";
 import { holdsQueue, settingUp } from "../sessions/setup-progress";
 import { firstMessageId, launchPending } from "../tasks/launch-gate";
 import type { ChatItem, FileSuggestion } from "./events";
@@ -280,6 +281,7 @@ async function ensureLive(sessionId: string, spawn = true): Promise<Live> {
       build: hello.build,
       canPlan: !!hello.caps?.includes("plan"),
       canQueue: !!hello.caps?.includes("queue"),
+      canFresh: !!hello.caps?.includes("fresh"),
     };
     // From an older build and busy, or running background work: it goes at
     // its next turn boundary, by itself if it can. Messages meanwhile wait
@@ -716,6 +718,54 @@ function retire(sessionId: string, live: Live, resume = true): void {
   if (resume) void resumeQueue(sessionId);
 }
 
+// A fresh start the reader asked for, by the path the context threshold
+// takes (the worker's endConversation): "now" when nothing is running, else
+// "after-turn", at the next turn boundary. The next worker reads the brief
+// and permissions as the server has them then, nothing held over.
+export class FreshRefusal extends Error {}
+
+export async function freshStartChat(
+  sessionId: string
+): Promise<"now" | "after-turn"> {
+  const session = getSession(sessionId);
+  // A terminal agent's conversation isn't ours to release: it keeps running.
+  if (session.view !== "chat" || session.archived_at)
+    throw new FreshRefusal("Only an open chat session can start fresh");
+  try {
+    checkChattable(session);
+  } catch (e) {
+    throw new FreshRefusal(e instanceof Error ? e.message : String(e));
+  }
+  const live =
+    registry.live.get(sessionId) ??
+    (runningWorkers().includes(sessionId)
+      ? await ensureLive(sessionId, false).catch(() => undefined)
+      : undefined);
+  if (live) {
+    // A worker from before this existed would ignore the command.
+    if (live.canFresh) {
+      live.worker.command({ type: "fresh" });
+      return live.state === "idle" && !live.activity.tasks.size
+        ? "now"
+        : "after-turn";
+    }
+    if (live.state !== "idle")
+      throw new FreshRefusal("Try again when the current turn has ended");
+    stopChat(sessionId);
+  }
+  releaseConversation(sessionId, REQUESTED_FRESH);
+  const item: ChatItem = {
+    id: `note-refresh-${Date.now()}`,
+    kind: "note",
+    tone: "note",
+    text: `Fresh start: the agent starts a new conversation with its brief${session.role === "orchestrator" ? " and the current state from AgentOS" : ""} at its next message.`,
+    createdAt: Date.now(),
+  };
+  saveItem(sessionId, item);
+  emit(sessionId, { type: "item", item });
+  return "now";
+}
+
 export function stopChat(sessionId: string): void {
   const live = registry.live.get(sessionId);
   if (live) {

package/lib/chat/worker/host.ts

@@ -41,7 +41,13 @@ import {
   visualsTools,
 } from "../../artifacts/tools";
 import type { RoleExtras } from "./extras";
-import { compactThreshold, refreshSettings, refreshedNote } from "../refresh";
+import {
+  REQUESTED_FRESH,
+  compactThreshold,
+  refreshSettings,
+  refreshedNote,
+  releaseConversation,
+} from "../refresh";
 import { compactContext } from "../compact-context";
 import { COMPACT_BRIEF, COMPACT_INSTRUCTIONS } from "../working-state";
 import { compactionDue, staleLabel, type Staleness } from "../stale";
@@ -679,11 +685,32 @@ export class ChatHost {
       case "retire":
         this.retiring = true;
         return this.retireIfDone();
+      case "fresh":
+        return this.freshOnRequest();
       case "close":
         return this.close();
     }
   }
 
+  // A fresh start the reader asked for: the same retire as at the context
+  // threshold, so it waits for the turn boundary and says so meanwhile.
+  private freshOnRequest(): void {
+    if (this.refreshAt || this.closed) return;
+    this.refreshAt = REQUESTED_FRESH;
+    this.retiring = true;
+    this.retireWaited = true;
+    this.retireIfDone();
+    // Still here: a turn, background work or its rest timer holds it.
+    if (!this.closed)
+      this.record({
+        id: `note-fresh-pending-${Date.now()}`,
+        kind: "note",
+        tone: "note",
+        text: "Starts fresh after this turn",
+        createdAt: Date.now(),
+      });
+  }
+
   private hardStopped(): boolean {
     return this.hardStopAt > 0 && Date.now() - this.hardStopAt < HARD_STOP_MS;
   }
@@ -849,20 +876,19 @@ export class ChatHost {
   // with the brief and tells it why. The chat Saad reads goes on, with a
   // line saying where it started over.
   private endConversation(): void {
-    db.prepare(
-      `UPDATE sessions SET claude_session_id = NULL, chat_resume_at = NULL,
-         chat_suggestion = NULL, chat_context = NULL, chat_restarted = 0,
-         chat_refreshed = ? WHERE id = ?`
-    ).run(this.refreshAt, this.session.id);
+    releaseConversation(this.session.id, this.refreshAt);
     const brief = `its brief${this.session.role === "orchestrator" ? " and the current state from AgentOS" : ""}`;
     const stale = this.staleRefresh;
+    const requested = this.refreshAt === REQUESTED_FRESH;
     this.record({
       id: `note-refresh-${Date.now()}`,
       kind: "note",
       tone: "note",
-      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.`,
+      text: requested
+        ? `Fresh start: the agent starts a new conversation with ${brief} at its next message.`
+        : 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)

package/lib/chat/worker/main.ts

@@ -75,7 +75,7 @@ async function main(sessionId: string) {
         build: buildId(),
         state: host.state,
         streaming: [...host.streaming.values()],
-        caps: ["plan", "queue", "retire"],
+        caps: ["plan", "queue", "retire", "fresh"],
       } satisfies WorkerEvent)}\n`
     );
     client.on(

package/lib/chat/worker/protocol.ts

@@ -58,6 +58,10 @@ export type WorkerCommand =
   // wait in the queue) and closes at its next turn boundary, so a current
   // worker resumes the conversation with today's tools.
   | { type: "retire" }
+  // The reader asked for a fresh conversation: at the next turn boundary
+  // (now, if idle) the agent's conversation ends and the next worker
+  // starts a new one with today's brief and permissions.
+  | { type: "fresh" }
   | { type: "close" };
 
 // Worker -> server: what's live right now on connecting, then events.

package/package.json

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