@saadnvd1/agent-os 0.3.649 → 0.3.653

package/components/Chat/ChatPanel.tsx

@@ -43,10 +43,11 @@ import { LearningCardsHost } from "@/components/LearningCards/LearningCard";
 import { composerCompacts } from "@/lib/chat/stale";
 import { useFreshStartQuery } from "@/data/fresh-start";
 import { QuoteButton } from "./QuoteButton";
+import { quoteIntoComposer } from "./quote-selection";
 import { ToolBodies, ToolGroup } from "./Tools";
 import { RowState, RowStore } from "./rowState";
+import { useKeybindings } from "@/hooks/useKeybindings";
 import { Background, type BackgroundValue } from "./background";
-import { backgroundKey } from "@/lib/chat/background";
 import { FindBar } from "./FindBar";
 import { FIND_EVENT, isFindKey, useFind } from "./useFind";
 import { McpServers } from "./McpServers";
@@ -365,6 +366,15 @@ export function ChatPanel({
         ?.focus(),
     []
   );
+  // Quote button or Enter: the text goes in, and the caret is ready to reply.
+  const quote = (text: string) =>
+    quoteIntoComposer(
+      text,
+      // After the draft, so the caret ends at the end of the composer.
+      (t) =>
+        setInsert({ text: quoteMarkdown(t), at: Date.now(), append: true }),
+      focusComposer
+    );
   const togglePlan = plan === null ? undefined : () => setPlan(!plan);
   const sendText = (text: string) => {
     toEnd();
@@ -377,39 +387,24 @@ export function ChatPanel({
   const asIs = asIsFor === sessionId;
   const setAsIs = (on: boolean) => setAsIsFor(on ? sessionId : null);
 
+  const inPanel = (e: KeyboardEvent) =>
+    !!rootRef.current?.contains(e.target as Node);
   // Shift+Tab switches plan mode from the composer, as in the terminal.
-  const shiftTab = useRef(togglePlan);
-  useEffect(() => {
-    shiftTab.current = togglePlan;
-  });
-  useEffect(() => {
-    const onKey = (e: KeyboardEvent) => {
-      if (e.key !== "Tab" || !e.shiftKey || e.metaKey || e.ctrlKey) return;
-      const target = e.target as HTMLElement;
-      if (
-        !shiftTab.current ||
-        !rootRef.current?.contains(target) ||
-        !(target === rootRef.current || target.closest(".chat-composer"))
-      )
-        return;
-      e.preventDefault();
-      shiftTab.current();
-    };
-    window.addEventListener("keydown", onKey, true);
-    return () => window.removeEventListener("keydown", onKey, true);
-  }, []);
-
-  useChatCommands({
-    sessionId,
-    connected,
-    running,
-    context,
-    plan,
-    send: sendText,
-    setPlan,
-    interrupt,
-    focusComposer,
-  });
+  useKeybindings(`chat-plan:${sessionId}`, [
+    {
+      id: "chat.plan",
+      keys: "shift+tab",
+      when: (e) => {
+        const target = e.target as HTMLElement;
+        return (
+          !!togglePlan &&
+          inPanel(e) &&
+          (target === rootRef.current || !!target.closest(".chat-composer"))
+        );
+      },
+      run: () => togglePlan?.(),
+    },
+  ]);
 
   const blocks = useMemo(
     () => groupTimeline(items, { foldEvents: !!orchestratorOf }),
@@ -466,20 +461,27 @@ export function ChatPanel({
       ),
     [canBackground, foregroundTasks]
   );
-  const moveRef = useRef({ canMove, backgroundTask });
-  useEffect(() => {
-    moveRef.current = { canMove, backgroundTask };
+  useKeybindings(`chat:${sessionId}`, [
+    {
+      id: "chat.background",
+      keys: "ctrl+b",
+      when: (e) => canMove && inPanel(e),
+      run: () => backgroundTask(),
+    },
+  ]);
+  useChatCommands({
+    sessionId,
+    connected,
+    running,
+    context,
+    plan,
+    send: sendText,
+    setPlan,
+    interrupt,
+    focusComposer,
+    background: canMove ? () => backgroundTask() : undefined,
   });
-  useEffect(() => {
-    const onKey = (e: KeyboardEvent) => {
-      if (!rootRef.current?.contains(e.target as Node)) return;
-      if (!backgroundKey(e, moveRef.current.canMove)) return;
-      e.preventDefault();
-      moveRef.current.backgroundTask();
-    };
-    window.addEventListener("keydown", onKey, true);
-    return () => window.removeEventListener("keydown", onKey, true);
-  }, []);
+
   const itemsById = useMemo(
     () => new Map(items.map((i) => [i.id, i])),
     [items]
@@ -790,12 +792,7 @@ export function ChatPanel({
           onStop={stopTask}
           onLoadOutput={loadTaskOutput}
         />
-        <QuoteButton
-          rootRef={scrollRef}
-          onQuote={(text) =>
-            setInsert({ text: quoteMarkdown(text), at: Date.now() })
-          }
-        />
+        <QuoteButton rootRef={scrollRef} onQuote={quote} />
         <PausedBanner sessionId={sessionId} />
         <Queue
           queue={queue}

package/components/Chat/QuoteButton.tsx

@@ -1,10 +1,17 @@
 "use client";
 
-import { useEffect, useState, type RefObject } from "react";
+import { useEffect, useId, useState, type RefObject } from "react";
 import { Quote } from "lucide-react";
 import { cn } from "@/lib/utils";
 import { useCoarsePointer } from "./composer/useCoarsePointer";
-import { placeQuote, quotePick, type Placement } from "./quote-selection";
+import { useKeybindings } from "@/hooks/useKeybindings";
+import {
+  quoteAction,
+  quoteEnter,
+  placeQuote,
+  quotePick,
+  type Placement,
+} from "./quote-selection";
 
 interface Picked {
   text: string;
@@ -57,12 +64,16 @@ export function QuoteButton({
     };
   }, [rootRef]);
 
+  const shown = !!picked && (coarse || !!picked.at);
+  const quote = quoteAction(picked?.text, {
+    onQuote,
+    clearSelection: () => window.getSelection()?.removeAllRanges(),
+    hide: () => setPicked(null),
+  });
+  // One source per button: each open chat pane has its own.
+  useKeybindings(`chat-quote:${useId()}`, [quoteEnter(shown, quote)]);
+
   if (!picked) return null;
-  const quote = () => {
-    onQuote(picked.text);
-    window.getSelection()?.removeAllRanges();
-    setPicked(null);
-  };
   const button = (
     <button
       type="button"
@@ -73,6 +84,12 @@ export function QuoteButton({
     >
       <Quote className="h-3.5 w-3.5" />
       Quote
+      <kbd
+        aria-hidden
+        className="text-muted-foreground bg-muted hidden rounded px-1 font-mono text-[10px] leading-4 md:inline"
+      >
+        ↵
+      </kbd>
     </button>
   );
   if (coarse)

package/components/Chat/composer/editor.test.ts

@@ -55,13 +55,25 @@ const keys = (over: Partial<KeyHandlers> = {}): KeyHandlers => ({
 
 function press(
   key: string,
-  opts: { shift?: boolean; coarse?: boolean } = {},
+  opts: {
+    shift?: boolean;
+    coarse?: boolean;
+    alt?: boolean;
+    ctrl?: boolean;
+    meta?: boolean;
+  } = {},
   h = keys()
 ) {
   window.matchMedia = ((q: string) => ({
     matches: Boolean(opts.coarse) && q.includes("coarse"),
   })) as never;
-  const event = new KeyboardEvent("keydown", { key, shiftKey: opts.shift });
+  const event = new KeyboardEvent("keydown", {
+    key,
+    shiftKey: opts.shift,
+    altKey: opts.alt,
+    ctrlKey: opts.ctrl,
+    metaKey: opts.meta,
+  });
   if (!handleKeyDown(editor, event, h)) {
     editor.view.someProp("handleKeyDown", (f) => f(editor.view, event));
   }
@@ -289,6 +301,31 @@ describe("Enter", () => {
     expect(taken).toBe(2);
   });
 
+  it("→ leaves the caret alone with no suggestion, a modifier, or an open menu", () => {
+    make();
+    let taken = 0;
+    const on = keys({ suggestion: true, onAcceptSuggestion: () => taken++ });
+    const off = keys({ suggestion: false, onAcceptSuggestion: () => taken++ });
+    press("ArrowRight", {}, off);
+    for (const mod of [
+      { shift: true },
+      { alt: true },
+      { ctrl: true },
+      { meta: true },
+    ])
+      press("ArrowRight", mod, on);
+    const open = keys({
+      suggestion: true,
+      menuOpen: true,
+      menuHasMatches: true,
+      onAcceptSuggestion: () => taken++,
+    });
+    press("ArrowRight", {}, open);
+    expect(taken).toBe(0);
+    press("ArrowRight", {}, on);
+    expect(taken).toBe(1);
+  });
+
   it("Tab picks from an open menu before taking ghost text", () => {
     make();
     const got: string[] = [];

package/components/Chat/quote-selection.test.ts

@@ -1,6 +1,14 @@
 import { JSDOM } from "jsdom";
-import { beforeEach, describe, expect, it } from "vitest";
-import { placeQuote, quotePick, rangeText } from "./quote-selection";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { KeybindingRegistry } from "@/lib/keybindings/registry";
+import {
+  placeQuote,
+  quoteAction,
+  quoteEnter,
+  quoteIntoComposer,
+  quotePick,
+  rangeText,
+} from "./quote-selection";
 
 // The suite's setup needs node, so the DOM is built here.
 const { window } = new JSDOM("<!doctype html><body></body>");
@@ -165,3 +173,177 @@ describe("placeQuote", () => {
     ).toBeNull();
   });
 });
+
+describe("Enter quotes", () => {
+  let root: HTMLElement;
+  beforeEach(() => {
+    root = chat();
+  });
+
+  const reply = () => text("#a2 p", 1);
+  const key = (target: EventTarget, extra: object = {}) =>
+    ({
+      key: "Enter",
+      code: "Enter",
+      target,
+      ctrlKey: false,
+      metaKey: false,
+      altKey: false,
+      shiftKey: false,
+      isComposing: false,
+      repeat: false,
+      preventDefault() {},
+      ...extra,
+    }) as unknown as KeyboardEvent;
+
+  // Runs a key through a real registry holding the binding.
+  function press(shown: boolean, e: KeyboardEvent) {
+    const run = vi.fn();
+    const reg = new KeybindingRegistry({
+      addEventListener() {},
+      removeEventListener() {},
+    });
+    reg.register("t", [quoteEnter(shown, run, () => window.getSelection())]);
+    return { handled: reg.handle(e), run };
+  }
+
+  it("fires with a selection in a reply and the button showing", () => {
+    select([reply(), 4], [reply(), 8]);
+    const { handled, run } = press(true, key(root));
+    expect(handled).toBe(true);
+    expect(run).toHaveBeenCalledOnce();
+  });
+
+  it("leaves Enter alone when the button isn't showing", () => {
+    select([reply(), 4], [reply(), 8]);
+    expect(press(false, key(root)).handled).toBe(false);
+  });
+
+  it("leaves Enter alone with no selection", () => {
+    window.getSelection()!.removeAllRanges();
+    expect(press(true, key(root)).handled).toBe(false);
+  });
+
+  it("leaves Enter alone in the composer, key or selection", () => {
+    const composer = document.getElementById("composer") as HTMLTextAreaElement;
+    select([reply(), 4], [reply(), 8]);
+    expect(press(true, key(composer)).handled).toBe(false);
+    composer.select();
+    select([composer.parentNode!, 0], [composer.parentNode!, 1]);
+    const inside = document.createElement("div");
+    inside.setAttribute("contenteditable", "true");
+    inside.textContent = "draft";
+    document.body.append(inside);
+    select([inside.firstChild!, 0], [inside.firstChild!, 3]);
+    expect(press(true, key(root)).handled).toBe(false);
+  });
+
+  it("leaves a focused button to its own Enter", () => {
+    select([reply(), 4], [reply(), 8]);
+    const button = document.querySelector("#a2 button")!;
+    expect(press(true, key(button)).handled).toBe(false);
+  });
+
+  it.each(["shiftKey", "metaKey", "ctrlKey", "altKey"])(
+    "ignores Enter with %s",
+    (mod) => {
+      select([reply(), 4], [reply(), 8]);
+      expect(press(true, key(root, { [mod]: true })).handled).toBe(false);
+    }
+  );
+
+  it("ignores IME composition and repeats", () => {
+    select([reply(), 4], [reply(), 8]);
+    expect(press(true, key(root, { isComposing: true })).handled).toBe(false);
+    expect(press(true, key(root, { repeat: true })).handled).toBe(false);
+  });
+});
+
+describe("quoteIntoComposer", () => {
+  it("puts the text in, then focuses the composer", () => {
+    const order: string[] = [];
+    quoteIntoComposer(
+      "hello",
+      (t) => order.push(`put:${t}`),
+      () => order.push("focus")
+    );
+    expect(order).toEqual(["put:hello", "focus"]);
+  });
+});
+
+describe("Enter quoting wiring", () => {
+  const sel = () => window.getSelection()!;
+  const enter = (): KeyboardEvent =>
+    ({
+      key: "Enter",
+      code: "Enter",
+      target: document.body,
+      ctrlKey: false,
+      metaKey: false,
+      altKey: false,
+      shiftKey: false,
+      isComposing: false,
+      repeat: false,
+      preventDefault() {},
+    }) as unknown as KeyboardEvent;
+  const registry = () =>
+    new KeybindingRegistry({
+      addEventListener() {},
+      removeEventListener() {},
+    });
+  const pick = () => {
+    const root = chat();
+    select([text("#a2 p", 1), 4], [text("#a2 p", 1), 8]);
+    return root;
+  };
+
+  it("Enter hands the text over, clears the selection, hides, focuses", () => {
+    pick();
+    const calls: string[] = [];
+    const action = quoteAction("very", {
+      onQuote: (t) =>
+        quoteIntoComposer(
+          t,
+          (m) => calls.push(`put:${m}`),
+          () => calls.push("focus")
+        ),
+      clearSelection: () => {
+        sel().removeAllRanges();
+        calls.push("clear");
+      },
+      hide: () => calls.push("hide"),
+    });
+    const reg = registry();
+    reg.register("a", [quoteEnter(true, action, sel)]);
+    expect(reg.handle(enter())).toBe(true);
+    expect(calls).toEqual(["put:very", "focus", "clear", "hide"]);
+    expect(sel().isCollapsed).toBe(true);
+  });
+
+  it("does nothing without picked text", () => {
+    const onQuote = vi.fn();
+    quoteAction(undefined, {
+      onQuote,
+      clearSelection: vi.fn(),
+      hide: vi.fn(),
+    })();
+    expect(onQuote).not.toHaveBeenCalled();
+  });
+
+  it("keeps one binding per source: panes don't replace each other", () => {
+    pick();
+    const reg = registry();
+    const a = vi.fn();
+    const b = vi.fn();
+    const offA = reg.register("chat-quote:a", [quoteEnter(true, a, sel)]);
+    const offB = reg.register("chat-quote:b", [quoteEnter(false, b, sel)]);
+    expect(reg.handle(enter())).toBe(true);
+    expect(a).toHaveBeenCalledOnce();
+    expect(b).not.toHaveBeenCalled();
+    offB();
+    expect(reg.handle(enter())).toBe(true);
+    expect(a).toHaveBeenCalledTimes(2);
+    offA();
+    expect(reg.handle(enter())).toBe(false);
+  });
+});

package/components/Chat/quote-selection.ts

@@ -1,3 +1,4 @@
+import type { Keybinding } from "@/lib/keybindings/registry";
 // What a selection in the chat quotes: the parts of it inside replies
 // (elements marked data-quotable), whatever its ends touch. A triple-click
 // or a drag past a reply's last line ends the range outside the reply, in
@@ -114,3 +115,72 @@ export function placeQuote(sel: Box, view: Box, size = 48): Placement | null {
     side: "below",
   };
 }
+
+const TYPES_OR_ACTS =
+  'input, textarea, select, button, a[href], summary, [contenteditable]:not([contenteditable="false"])';
+
+function inTypingOrAction(node: Node | null): boolean {
+  const el =
+    node && (node.nodeType === 1 ? (node as Element) : node.parentElement);
+  return !!el?.closest(TYPES_OR_ACTS);
+}
+
+// Whether Enter quotes: the button is showing for a live selection, and
+// neither the key's target nor the selection sits in the composer or any
+// other field, where Enter keeps its own meaning.
+export function enterQuotes(
+  visible: boolean,
+  target: EventTarget | null,
+  sel: Selection | null
+): boolean {
+  if (!visible || !sel || sel.isCollapsed || !sel.rangeCount) return false;
+  if (!sel.toString().trim()) return false;
+  return (
+    !inTypingOrAction(target as Node | null) &&
+    !inTypingOrAction(sel.anchorNode) &&
+    !inTypingOrAction(sel.focusNode)
+  );
+}
+
+// What Quote does, from the button or from Enter: the text goes in the
+// composer, then the composer takes the caret so a reply can follow.
+export function quoteIntoComposer(
+  text: string,
+  put: (markdown: string) => void,
+  focus: () => void
+) {
+  put(text);
+  focus();
+}
+
+// Enter does what the Quote button does, while it's showing.
+export function quoteEnter(
+  shown: boolean,
+  run: () => void,
+  getSel: () => Selection | null = () => window.getSelection()
+): Keybinding {
+  return {
+    id: "chat.quote",
+    keys: "enter",
+    when: (e) => enterQuotes(shown, e.target, getSel()),
+    run,
+  };
+}
+
+// What the button does with the picked text, by click or by Enter: hand it
+// over, clear the selection, hide the button.
+export function quoteAction(
+  text: string | undefined,
+  io: {
+    onQuote: (text: string) => void;
+    clearSelection: () => void;
+    hide: () => void;
+  }
+) {
+  return () => {
+    if (text === undefined) return;
+    io.onQuote(text);
+    io.clearSelection();
+    io.hide();
+  };
+}

package/components/Chat/useChatCommands.ts

@@ -2,7 +2,7 @@
 
 import { useEffect, useRef } from "react";
 import { useSnapshot } from "valtio";
-import { ListChecks, Minimize2, Square } from "lucide-react";
+import { Layers, ListChecks, Minimize2, Square } from "lucide-react";
 import type { ChatContext } from "@/lib/chat/events";
 import { usePaletteCommands } from "@/hooks/usePaletteCommands";
 import { chatMeta, chatMetaActions, type ChatActions } from "@/stores/chatMeta";
@@ -15,6 +15,7 @@ export function useChatCommands({
   running,
   context,
   plan,
+  background,
   ...handlers
 }: ChatActions & {
   sessionId: string;
@@ -22,10 +23,12 @@ export function useChatCommands({
   running: boolean;
   context: ChatContext | null;
   plan: boolean | null;
+  // Set while a running call can move to the background.
+  background?: () => void;
 }) {
-  const latest = useRef(handlers);
+  const latest = useRef({ ...handlers, background });
   useEffect(() => {
-    latest.current = handlers;
+    latest.current = { ...handlers, background };
   });
 
   useEffect(() => {
@@ -69,6 +72,19 @@ export function useChatCommands({
             icon: Minimize2,
             run: () => latest.current.send("/compact"),
           },
+          ...(background
+            ? [
+                {
+                  id: "chat.background",
+                  title: "Run in background",
+                  group: "Chat",
+                  keywords: ["move", "detach", "task"],
+                  hint: "Ctrl+B",
+                  icon: Layers,
+                  run: () => latest.current.background?.(),
+                },
+              ]
+            : []),
           ...(running
             ? [
                 {

package/components/SessionList/OrchestratorPinRow.tsx

@@ -56,6 +56,7 @@ export const OrchestratorPinRow = memo(function OrchestratorPinRow({
 
   const content = (
     <RowFrame
+      data-session-row={session.id}
       data-tip={`${label}\n${summary}`}
       onActivate={() => !renaming && ctx.onSelect(session.id)}
       className={

package/components/SessionList/SessionRow.tsx

@@ -76,7 +76,7 @@ export const SessionRow = memo(function SessionRow({
   );
 
   return (
-    <div>
+    <div data-session-row={session.id}>
       <RowShell
         title={session.name}
         tipKey={`session:${session.id}`}

package/components/SessionList/SessionShelves.tsx

@@ -8,6 +8,7 @@ import {
   doneSummary,
   type Shelves,
 } from "@/lib/sidebar/shelves";
+import { shownShelves } from "@/lib/sidebar/visible-order";
 import type { MachineGroup } from "@/lib/sidebar/machines";
 import { sidebarUiActions } from "@/stores/sidebarUi";
 import { cn } from "@/lib/utils";
@@ -124,8 +125,10 @@ export function SessionShelves({
   snoozedCollapsed: boolean;
   donePages: number;
 }) {
+  const folds = { doneCollapsed, snoozedCollapsed, donePages };
   const shown = shelves.done.slice(0, doneLimit(donePages));
   const hidden = shelves.done.length - shown.length;
+  const visible = shownShelves(shelves, folds);
   const pendingCards = usePendingCardSessions();
   const doneCards = shelves.done.reduce(
     (n, r) => n + (pendingCards.get(r.session.id) ?? 0),
@@ -210,10 +213,9 @@ export function SessionShelves({
             collapsed={snoozedCollapsed}
             onToggle={sidebarUiActions.toggleSnoozed}
           />
-          {!snoozedCollapsed &&
-            shelves.snoozed.map((r) => (
-              <SessionRow key={r.session.id} row={r} muted />
-            ))}
+          {visible.snoozed.map((r) => (
+            <SessionRow key={r.session.id} row={r} muted />
+          ))}
         </section>
       )}
       {shelves.done.length > 0 && (
@@ -223,8 +225,9 @@ export function SessionShelves({
             collapsed={doneCollapsed}
             onToggle={sidebarUiActions.toggleDone}
           />
-          {!doneCollapsed &&
-            shown.map((r) => <SessionRow key={r.session.id} row={r} muted />)}
+          {visible.done.map((r) => (
+            <SessionRow key={r.session.id} row={r} muted />
+          ))}
           {!doneCollapsed && hidden > 0 && (
             <button
               type="button"

package/components/SessionList/index.tsx

@@ -7,12 +7,13 @@ import { useDocsWorkspace } from "@/data/lumifyhub/docs";
 import { useFreshStart, usePinSession } from "@/data/sessions";
 import { useOrchestratorsQuery } from "@/data/orchestrators";
 import { docsUiActions } from "@/stores/docsUi";
-import type { SidebarRow } from "@/lib/sidebar/shelves";
+import { visibleSessionIds } from "@/lib/sidebar/visible-order";
 import type { OrchestratorOverview } from "@/lib/orchestrator/overview";
 import { useSessionListMutations } from "./hooks/useSessionListMutations";
 import { useBulkDelete } from "./hooks/useBulkDelete";
 import { useSidebarData } from "./useSidebarData";
 import { useSessionTips } from "./useSessionTips";
+import { useSessionSwitching } from "./useSessionSwitching";
 import { RowProvider, type RowContextValue } from "./RowContext";
 import { SidebarHeader } from "./SidebarHeader";
 import { useAddProject } from "@/components/Projects/AddProject/useAddProject";
@@ -28,9 +29,6 @@ export type { SessionListProps } from "./SessionList.types";
 // Shared, so a query still loading doesn't hand rows a new array each render.
 const NO_ORCHESTRATORS: OrchestratorOverview[] = [];
 
-const flatten = (rows: SidebarRow[]): string[] =>
-  rows.flatMap((r) => [r.session.id, ...flatten(r.workers)]);
-
 // One flat list of the workspace's sessions, on shelves: Pinned, Needs
 // you, Working, In review, Done.
 export function SessionList({
@@ -59,19 +57,20 @@ export function SessionList({
 
   const orderedIds = useMemo(
     () =>
-      flatten([
-        ...shelves.orchestrators,
-        ...shelves.pinned,
-        ...shelves.needsYou,
-        ...shelves.working,
-        ...shelves.inReview,
-        ...shelves.ongoing,
-        ...shelves.snoozed,
-        ...shelves.done,
-        ...data.machines.flatMap((g) => g.rows),
-      ]),
-    [shelves, data.machines]
+      visibleSessionIds(shelves, data.machines, {
+        doneCollapsed: ui.doneCollapsed,
+        snoozedCollapsed: ui.snoozedCollapsed,
+        donePages: ui.donePages,
+      }),
+    [
+      shelves,
+      data.machines,
+      ui.doneCollapsed,
+      ui.snoozedCollapsed,
+      ui.donePages,
+    ]
   );
+  useSessionSwitching(orderedIds, activeSessionId, onSelect);
 
   // 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

package/components/SessionList/useSessionSwitching.ts

@@ -0,0 +1,55 @@
+"use client";
+
+import { MessageSquare } from "lucide-react";
+import { useKeybindings } from "@/hooks/useKeybindings";
+import { usePaletteCommands } from "@/hooks/usePaletteCommands";
+import { chordHint } from "@/lib/keybindings/chord";
+import { fieldOwnsKey } from "@/lib/keybindings/focus";
+import { neighbourSession } from "@/lib/sidebar/visible-order";
+
+const PREVIOUS = "mod+up";
+const NEXT = "mod+down";
+
+// ⌘↑ / ⌘↓ (Ctrl off a Mac) select the row above or below the active one, as
+// a click would, in the order the sidebar shows. Nothing happens at either end.
+export function useSessionSwitching(
+  orderedIds: string[],
+  activeSessionId: string | undefined,
+  onSelect: (id: string) => void
+) {
+  const step = (by: 1 | -1) => {
+    const id = neighbourSession(orderedIds, activeSessionId, by);
+    if (!id) return;
+    onSelect(id);
+    requestAnimationFrame(() =>
+      document
+        .querySelector(`[data-session-row="${CSS.escape(id)}"]`)
+        ?.scrollIntoView({ block: "nearest" })
+    );
+  };
+  const free = (e: KeyboardEvent) => !fieldOwnsKey(e.target);
+  useKeybindings("session-switching", [
+    { id: "session.previous", keys: PREVIOUS, when: free, run: () => step(-1) },
+    { id: "session.next", keys: NEXT, when: free, run: () => step(1) },
+  ]);
+  usePaletteCommands("session-switching", [
+    {
+      id: "session.previous",
+      title: "Previous session",
+      group: "Sessions",
+      hint: chordHint(PREVIOUS),
+      keywords: ["switch", "up"],
+      icon: MessageSquare,
+      run: () => step(-1),
+    },
+    {
+      id: "session.next",
+      title: "Next session",
+      group: "Sessions",
+      hint: chordHint(NEXT),
+      keywords: ["switch", "down"],
+      icon: MessageSquare,
+      run: () => step(1),
+    },
+  ]);
+}

package/hooks/useKeybindings.ts

@@ -0,0 +1,27 @@
+"use client";
+
+import { useEffect, useRef } from "react";
+import { keybindings, type Keybinding } from "@/lib/keybindings/registry";
+
+// Binds chords while the caller is mounted. `when` and `run` always see the
+// latest render, so callers don't memoise them.
+export function useKeybindings(source: string, bindings: Keybinding[]) {
+  const latest = useRef(bindings);
+  useEffect(() => {
+    latest.current = bindings;
+  });
+  const keys = bindings
+    .map((b) => `${b.id}:${b.keys}:${b.repeat ? 1 : 0}`)
+    .join("|");
+  useEffect(() => {
+    const at = (id: string) => latest.current.find((b) => b.id === id)!;
+    return keybindings.register(
+      source,
+      latest.current.map((b) => ({
+        ...b,
+        when: (e) => at(b.id).when?.(e) ?? true,
+        run: () => at(b.id).run(),
+      }))
+    );
+  }, [source, keys]);
+}

package/lib/chat/background.ts

@@ -24,28 +24,6 @@ export function backgroundable(
   );
 }
 
-// Ctrl+B, nothing else held, and only while there is something to move;
-// otherwise the key is left to the page.
-export function backgroundKey(
-  e: {
-    key: string;
-    ctrlKey: boolean;
-    metaKey: boolean;
-    altKey: boolean;
-    shiftKey: boolean;
-    repeat?: boolean;
-    isComposing?: boolean;
-  },
-  available: boolean
-): boolean {
-  return (
-    available &&
-    e.key.toLowerCase() === "b" &&
-    e.ctrlKey &&
-    !(e.metaKey || e.altKey || e.shiftKey || e.repeat || e.isComposing)
-  );
-}
-
 // Errors that mean the agent never got the request.
 const UNREACHED = new Set(["unsupported", "unavailable", "timeout"]);
 

package/lib/keybindings/chord.ts

@@ -0,0 +1,114 @@
+export interface Chord {
+  key: string;
+  ctrl: boolean;
+  meta: boolean;
+  alt: boolean;
+  shift: boolean;
+}
+
+export interface KeyLike {
+  key: string;
+  ctrlKey: boolean;
+  metaKey: boolean;
+  altKey: boolean;
+  shiftKey: boolean;
+}
+
+const MODS: Record<string, "ctrl" | "meta" | "alt" | "shift"> = {
+  ctrl: "ctrl",
+  control: "ctrl",
+  cmd: "meta",
+  meta: "meta",
+  alt: "alt",
+  option: "alt",
+  shift: "shift",
+};
+
+const KEY_NAMES: Record<string, string> = {
+  esc: "escape",
+  space: " ",
+  return: "enter",
+  up: "arrowup",
+  down: "arrowdown",
+  left: "arrowleft",
+  right: "arrowright",
+};
+
+export const isMac = () =>
+  typeof navigator !== "undefined" &&
+  /mac|iphone|ipad/i.test(navigator.platform);
+
+// "ctrl+b", "shift+tab", "meta+k". Modifiers must match exactly: ctrl+b is
+// not cmd+b and not ctrl+shift+b. "mod" is Cmd on a Mac and Ctrl elsewhere.
+export function parseChord(keys: string, mac: boolean = isMac()): Chord {
+  const chord: Chord = {
+    key: "",
+    ctrl: false,
+    meta: false,
+    alt: false,
+    shift: false,
+  };
+  for (const raw of keys.toLowerCase().split("+")) {
+    const part = raw.trim();
+    const mod = part === "mod" ? (mac ? "meta" : "ctrl") : MODS[part];
+    if (mod) chord[mod] = true;
+    else if (chord.key) throw new Error(`Two keys in chord "${keys}"`);
+    else chord.key = KEY_NAMES[part] ?? part;
+  }
+  if (!chord.key) throw new Error(`No key in chord "${keys}"`);
+  return chord;
+}
+
+export function matchChord(chord: Chord, e: KeyLike): boolean {
+  return (
+    e.key.toLowerCase() === chord.key &&
+    e.ctrlKey === chord.ctrl &&
+    e.metaKey === chord.meta &&
+    e.altKey === chord.alt &&
+    e.shiftKey === chord.shift
+  );
+}
+
+// "Ctrl+B" for display (the label users know from Claude Code).
+export function formatChord(keys: string): string {
+  return keys
+    .split("+")
+    .map((p) => {
+      const t = p.trim();
+      return t.length === 1
+        ? t.toUpperCase()
+        : t[0].toUpperCase() + t.slice(1).toLowerCase();
+    })
+    .join("+");
+}
+
+const SYMBOLS: Record<string, string> = {
+  up: "↑",
+  down: "↓",
+  left: "←",
+  right: "→",
+};
+
+// "mod+up" as a hint: "⌘↑" on a Mac, "Ctrl+↑" elsewhere.
+export function chordHint(keys: string, mac: boolean = isMac()): string {
+  const parts = keys.split("+").map((p) => p.trim().toLowerCase());
+  const label = (p: string) =>
+    SYMBOLS[p] ??
+    (p.length === 1 ? p.toUpperCase() : p[0].toUpperCase() + p.slice(1));
+  if (!mac)
+    return parts
+      .map((p) =>
+        p === "mod" || p === "cmd" || p === "meta" ? "Ctrl" : label(p)
+      )
+      .join("+");
+  const sym: Record<string, string> = {
+    mod: "⌘",
+    cmd: "⌘",
+    meta: "⌘",
+    ctrl: "⌃",
+    alt: "⌥",
+    option: "⌥",
+    shift: "⇧",
+  };
+  return parts.map((p) => sym[p] ?? label(p)).join("");
+}

package/lib/keybindings/focus.ts

@@ -0,0 +1,29 @@
+const NON_TEXT = new Set([
+  "checkbox",
+  "radio",
+  "button",
+  "submit",
+  "reset",
+  "range",
+  "color",
+  "file",
+  "image",
+]);
+
+// Whether a vertical-arrow chord should be left to the focused field: it has
+// text, so ⌘↑/⌘↓ move its caret. An empty field, a terminal, or no field
+// at all lets the app have the key. A dialog (the palette) keeps its keys.
+export function fieldOwnsKey(target: EventTarget | null): boolean {
+  const el = target as HTMLElement | null;
+  if (!el || typeof el.closest !== "function") return false;
+  if (el.closest(".xterm")) return false;
+  if (el.closest('[role="dialog"]')) return true;
+  const tag = el.tagName;
+  if (tag === "TEXTAREA") return (el as HTMLTextAreaElement).value.length > 0;
+  if (tag === "INPUT") {
+    const input = el as HTMLInputElement;
+    return !NON_TEXT.has(input.type) && input.value.length > 0;
+  }
+  if (el.isContentEditable) return (el.textContent ?? "").trim().length > 0;
+  return false;
+}

package/lib/keybindings/registry.ts

@@ -0,0 +1,84 @@
+import { matchChord, parseChord, type Chord, type KeyLike } from "./chord";
+
+/**
+ * Key chords tied to commands. Features register theirs under a source name
+ * and take them back the same way; one keydown listener serves them all.
+ *
+ * To add a shortcut, add one line to the `useKeybindings` call of the
+ * feature that owns the action: { id, keys: "ctrl+b", when, run }.
+ */
+export interface Keybinding {
+  id: string;
+  // "ctrl+b", "shift+tab", "esc": modifiers must match exactly.
+  keys: string;
+  // Whether it applies right now. The key is left alone when it doesn't.
+  when?: (e: KeyboardEvent) => boolean;
+  // Also fire while the key is held down.
+  repeat?: boolean;
+  run: () => void;
+}
+
+interface Compiled {
+  binding: Keybinding;
+  chord: Chord;
+}
+
+export class KeybindingRegistry {
+  private sources = new Map<string, Compiled[]>();
+  private attached = false;
+
+  constructor(
+    private target: Pick<Window, "addEventListener" | "removeEventListener">
+  ) {}
+
+  // Replaces what a source binds; returns how to take it back.
+  register(source: string, bindings: Keybinding[]): () => void {
+    const compiled = bindings.map((binding) => ({
+      binding,
+      chord: parseChord(binding.keys),
+    }));
+    this.sources.set(source, compiled);
+    this.attach();
+    return () => {
+      if (this.sources.get(source) !== compiled) return;
+      this.sources.delete(source);
+      if (!this.sources.size) this.detach();
+    };
+  }
+
+  // Runs the first binding whose chord matches and whose `when` holds, and
+  // reports whether one did (the caller then stops the key).
+  handle(e: KeyboardEvent): boolean {
+    for (const list of this.sources.values())
+      for (const { binding, chord } of list) {
+        if (!matchChord(chord, e as KeyLike)) continue;
+        if (e.isComposing || (e.repeat && !binding.repeat)) continue;
+        if (binding.when && !binding.when(e)) continue;
+        e.preventDefault();
+        binding.run();
+        return true;
+      }
+    return false;
+  }
+
+  private onKey = (e: Event) => {
+    this.handle(e as KeyboardEvent);
+  };
+
+  private attach() {
+    if (this.attached) return;
+    this.attached = true;
+    this.target.addEventListener("keydown", this.onKey, true);
+  }
+
+  private detach() {
+    this.attached = false;
+    this.target.removeEventListener("keydown", this.onKey, true);
+  }
+}
+
+export const keybindings = new KeybindingRegistry(
+  typeof window === "undefined"
+    ? { addEventListener() {}, removeEventListener() {} }
+    : window
+);

package/lib/sidebar/visible-order.ts

@@ -0,0 +1,56 @@
+import type { MachineGroup } from "./machines";
+import { doneLimit, type Shelves, type SidebarRow } from "./shelves";
+
+export interface ShelfFolds {
+  doneCollapsed: boolean;
+  snoozedCollapsed: boolean;
+  donePages: number;
+}
+
+// The Snoozed and Done rows the sidebar draws: none while folded, Done cut
+// to the pages shown. SessionShelves renders from this too, so the two agree.
+export function shownShelves(shelves: Shelves, folds: ShelfFolds) {
+  return {
+    snoozed: folds.snoozedCollapsed ? [] : shelves.snoozed,
+    done: folds.doneCollapsed
+      ? []
+      : shelves.done.slice(0, doneLimit(folds.donePages)),
+  };
+}
+
+const flatten = (rows: SidebarRow[]): string[] =>
+  rows.flatMap((r) => [r.session.id, ...flatten(r.workers)]);
+
+// Session ids top to bottom, as the sidebar draws them: folded shelves are
+// out, a conductor's workers follow it. The one order for switching sessions.
+export function visibleSessionIds(
+  shelves: Shelves,
+  machines: MachineGroup[],
+  folds: ShelfFolds
+): string[] {
+  const shown = shownShelves(shelves, folds);
+  return flatten([
+    ...shelves.orchestrators,
+    ...shelves.pinned,
+    ...shelves.needsYou,
+    ...shelves.working,
+    ...shelves.inReview,
+    ...shelves.ongoing,
+    ...shown.snoozed,
+    ...shown.done,
+    ...machines.flatMap((g) => g.rows),
+  ]);
+}
+
+// The neighbour of `activeId` one step up (-1) or down (1); null at either
+// end (no wrap), and the first or last row when nothing is active yet.
+export function neighbourSession(
+  ids: string[],
+  activeId: string | undefined,
+  step: 1 | -1
+): string | null {
+  if (!ids.length) return null;
+  const at = activeId ? ids.indexOf(activeId) : -1;
+  if (at < 0) return step === 1 ? ids[0] : ids[ids.length - 1];
+  return ids[at + step] ?? null;
+}

package/package.json

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