@saadnvd1/agent-os 0.3.777 → 0.3.779

package/app/api/live-shares/[id]/route.ts

@@ -3,6 +3,7 @@ import { z } from "zod";
 import { fail, readJson, refuseDemo, toResponse } from "@/lib/share/route";
 import {
   admit,
+  changeLevel,
   deny,
   dismissSuggestion,
   endLive,
@@ -15,6 +16,7 @@ const Action = z.discriminatedUnion("action", [
   z.object({ action: z.literal("admit"), guestId: z.string().min(1).max(64) }),
   z.object({ action: z.literal("deny"), guestId: z.string().min(1).max(64) }),
   z.object({ action: z.literal("kick"), guestId: z.string().min(1).max(64) }),
+  z.object({ action: z.literal("level"), level: z.enum(["watch", "suggest"]) }),
   z.object({
     action: z.literal("send"),
     suggestionId: z.string().min(1).max(64),
@@ -45,6 +47,7 @@ export async function POST(
     if (a.action === "admit") admit(id, a.guestId);
     else if (a.action === "deny") deny(id, a.guestId);
     else if (a.action === "kick") kick(id, a.guestId);
+    else if (a.action === "level") changeLevel(id, a.level);
     else if (a.action === "send")
       await sendSuggestion(id, a.suggestionId, a.text);
     else dismissSuggestion(id, a.suggestionId);

package/app/api/live-shares/route.test.ts

@@ -42,4 +42,19 @@ describe("live-shares routes", () => {
       400
     );
   });
+
+  it("accept watch and suggest only, and history as a boolean", async () => {
+    expect((await POST(req({ sessionId: "s", level: "drive" }))).status).toBe(
+      400
+    );
+    expect((await POST(req({ sessionId: "s", level: "root" }))).status).toBe(
+      400
+    );
+    expect((await POST(req({ sessionId: "s", history: "yes" }))).status).toBe(
+      400
+    );
+    expect(
+      (await act(req({ action: "level", level: "drive" }), ctx)).status
+    ).toBe(400);
+  });
 });

package/app/api/live-shares/route.ts

@@ -2,11 +2,13 @@ import { NextResponse } from "next/server";
 import { z } from "zod";
 import { linked, NOT_LINKED } from "@/lib/share/connect";
 import { fail, readJson, refuseDemo, toResponse } from "@/lib/share/route";
-import { createLive, listLive, startLive } from "@/lib/live/service";
+import { createLive, inviteFor, listLive, startLive } from "@/lib/live/service";
 
 const Create = z.object({
   sessionId: z.string().min(1).max(100),
   expiresIn: z.enum(["1h", "session"]).default("1h"),
+  level: z.enum(["watch", "suggest"]).default("suggest"),
+  history: z.boolean().default(true),
 });
 
 // POST /api/live-shares - mint a live link for one chat and start publishing.
@@ -19,7 +21,12 @@ export async function POST(request: Request) {
   if (!body.success) return fail("sessionId is required.", 400);
   if (!linked()) return fail(NOT_LINKED, 409);
   try {
-    const view = await createLive(body.data.sessionId, body.data.expiresIn);
+    const view = await createLive(
+      body.data.sessionId,
+      body.data.expiresIn,
+      body.data.level,
+      body.data.history
+    );
     return NextResponse.json(view, { status: 201 });
   } catch (err) {
     if ((err as Error).message === "Session not found")
@@ -36,5 +43,9 @@ export async function GET(request: Request) {
   startLive();
   const sessionId =
     new URL(request.url).searchParams.get("sessionId") ?? undefined;
-  return NextResponse.json({ linked: linked(), shares: listLive(sessionId) });
+  return NextResponse.json({
+    linked: linked(),
+    shares: listLive(sessionId),
+    ...(sessionId ? { invite: inviteFor(sessionId) } : {}),
+  });
 }

package/components/Live/InviteDialog.tsx

@@ -19,6 +19,8 @@ import {
   useEndLive,
   useLiveShare,
   type LiveExpiry,
+  type LiveInvite,
+  type LiveLevel,
   type LiveView,
 } from "@/data/live";
 import { EXPIRY_LABEL } from "@/lib/live/types";
@@ -47,8 +49,8 @@ function InviteBody({ sessionId }: { sessionId: string }) {
         <DialogTitle>Invite to watch live</DialogTitle>
         <DialogDescription>
           A guest opens the link, types a name and waits for you to let them in.
-          They see this chat as it happens, with secrets masked, and can suggest
-          a prompt. Nothing they type reaches the agent unless you tap Send.
+          They see this chat as it happens, with secrets masked. You choose what
+          else they can do.
         </DialogDescription>
       </div>
       {query.isPending ? (
@@ -60,15 +62,26 @@ function InviteBody({ sessionId }: { sessionId: string }) {
       ) : share ? (
         <Link share={share} />
       ) : (
-        <Create sessionId={sessionId} />
+        <Create sessionId={sessionId} invite={query.data.invite} />
       )}
     </DialogContent>
   );
 }
 
-function Create({ sessionId }: { sessionId: string }) {
+function Create({
+  sessionId,
+  invite,
+}: {
+  sessionId: string;
+  invite?: LiveInvite;
+}) {
   const [expiresIn, setExpiresIn] = useState<LiveExpiry>("1h");
+  const [level, setLevel] = useState<LiveLevel>("suggest");
+  const [history, setHistory] = useState<boolean | null>(null);
   const create = useCreateLive();
+  const options = invite?.levels ?? [];
+  const chosen = options.find((o) => o.value === level);
+  const withHistory = history ?? invite?.history.default ?? true;
   return (
     <>
       <div className="flex flex-col gap-1.5">
@@ -77,18 +90,34 @@ function Create({ sessionId }: { sessionId: string }) {
         </span>
         <Segmented
           label="Access"
-          value="watch"
-          onChange={() => {}}
-          options={[
-            { value: "watch", label: "Watch + suggest" },
-            { value: "drive", label: "Drive (later)" },
-          ]}
-          disabled
+          value={level}
+          onChange={setLevel}
+          options={options.map((o) => ({
+            value: o.value,
+            label: o.label,
+            hint: o.reason ?? o.hint,
+            disabled: !o.enabled,
+          }))}
         />
         <p className="text-muted-foreground text-xs">
-          Driving the agent from a guest link isn&apos;t available yet.
+          {chosen?.hint}
+          {options
+            .filter((o) => !o.enabled && o.reason)
+            .map((o) => ` ${o.label}: ${o.reason}.`)
+            .join("")}
         </p>
       </div>
+      {invite && (
+        <label className="flex min-h-11 items-center gap-3 text-sm">
+          <input
+            type="checkbox"
+            className="size-5"
+            checked={withHistory}
+            onChange={(e) => setHistory(e.target.checked)}
+          />
+          {invite.history.label}
+        </label>
+      )}
       <div className="flex flex-col gap-1.5">
         <span className="text-muted-foreground text-xs font-medium">
           The link works for
@@ -109,7 +138,9 @@ function Create({ sessionId }: { sessionId: string }) {
       <Button
         className="min-h-11"
         disabled={create.isPending}
-        onClick={() => create.mutate({ sessionId, expiresIn })}
+        onClick={() =>
+          create.mutate({ sessionId, expiresIn, level, history: withHistory })
+        }
       >
         <Users className="h-4 w-4" />
         {create.isPending ? "Creating…" : "Create invite link"}

package/components/Live/LiveChip.tsx

@@ -3,8 +3,9 @@
 import { useState } from "react";
 import { ChevronDown, Radio, UserMinus } from "lucide-react";
 import { Button } from "@/components/ui/button";
+import { Segmented } from "@/components/ui/segmented";
 import { StatusPill } from "@/components/ui/status-pill";
-import type { LiveView } from "@/data/live";
+import type { LiveLevel, LiveView } from "@/data/live";
 import { cn } from "@/lib/utils";
 
 export function presenceText(guests: LiveView["guests"]): string {
@@ -18,13 +19,15 @@ export function presenceText(guests: LiveView["guests"]): string {
 export function LiveChip({
   share,
   busy,
-  onKick,
+  onAction,
+  onLevel,
   onEnd,
   onInvite,
 }: {
   share: LiveView;
   busy: boolean;
-  onKick: (guestId: string) => void;
+  onAction: (guestId: string, kind: string) => void;
+  onLevel: (level: LiveLevel) => void;
   onEnd: () => void;
   onInvite: () => void;
 }) {
@@ -58,6 +61,21 @@ export function LiveChip({
           {share.notice && (
             <p className="text-muted-foreground px-2 text-xs">{share.notice}</p>
           )}
+          <Segmented
+            label="Access"
+            value={share.level}
+            onChange={onLevel}
+            disabled={busy}
+            options={share.levels.map((o) => ({
+              value: o.value,
+              label: o.label,
+              hint: o.reason ?? o.hint,
+              disabled: !o.enabled,
+            }))}
+          />
+          <p className="text-muted-foreground px-2 text-xs">
+            {share.levels.find((o) => o.value === share.level)?.hint}
+          </p>
           {admitted.length === 0 && (
             <p className="text-muted-foreground px-2 py-1 text-xs">
               No one has joined yet.
@@ -73,16 +91,19 @@ export function LiveChip({
                 aria-hidden
               />
               <span className="min-w-0 flex-1 truncate text-sm">{g.name}</span>
-              <Button
-                variant="ghost"
-                className="min-h-11"
-                disabled={busy}
-                onClick={() => onKick(g.id)}
-                aria-label={`Kick ${g.name}`}
-              >
-                <UserMinus className="h-4 w-4" />
-                Kick
-              </Button>
+              {g.actions.map((a) => (
+                <Button
+                  key={a.kind}
+                  variant="ghost"
+                  className="min-h-11"
+                  disabled={busy}
+                  onClick={() => onAction(g.id, a.kind)}
+                  aria-label={`${a.label} ${g.name}`}
+                >
+                  {a.kind === "kick" && <UserMinus className="h-4 w-4" />}
+                  {a.label}
+                </Button>
+              ))}
             </div>
           ))}
           <div className="flex gap-2 pt-1">

package/components/Live/LivePanel.tsx

@@ -25,14 +25,19 @@ export function LivePanel({
   if (!share) return null;
   const busy = act.isPending || end.isPending;
   const fail = (e: Error) => toast.error(e.message);
+  const doAction = (guestId: string, kind: string) => {
+    if (kind === "admit" || kind === "deny" || kind === "kick")
+      act.mutate({ action: kind, guestId }, { onError: fail });
+  };
   const lobby = share.guests.filter((g) => g.status === "pending");
   return (
     <div className="mx-auto flex w-full max-w-3xl flex-col gap-2 px-3 pb-2">
       <LiveChip
         share={share}
         busy={busy}
-        onKick={(guestId) =>
-          act.mutate({ action: "kick", guestId }, { onError: fail })
+        onAction={doAction}
+        onLevel={(level) =>
+          act.mutate({ action: "level", level }, { onError: fail })
         }
         onEnd={() => end.mutate(undefined, { onError: fail })}
         onInvite={() => liveUiActions.open(sessionId, title)}
@@ -42,12 +47,7 @@ export function LivePanel({
           key={g.id}
           guest={g}
           busy={busy}
-          onAdmit={() =>
-            act.mutate({ action: "admit", guestId: g.id }, { onError: fail })
-          }
-          onDeny={() =>
-            act.mutate({ action: "deny", guestId: g.id }, { onError: fail })
-          }
+          onAction={(kind) => doAction(g.id, kind)}
         />
       ))}
       {share.suggestions.map((s) => (

package/components/Live/LobbyCard.tsx

@@ -10,13 +10,11 @@ type Guest = LiveView["guests"][number];
 export function LobbyCard({
   guest,
   busy,
-  onAdmit,
-  onDeny,
+  onAction,
 }: {
   guest: Guest;
   busy: boolean;
-  onAdmit: () => void;
-  onDeny: () => void;
+  onAction: (kind: string) => void;
 }) {
   return (
     <div
@@ -41,23 +39,22 @@ export function LobbyCard({
         </div>
       </div>
       <div className="flex gap-2">
-        <Button
-          className="min-h-11 flex-1 sm:flex-none"
-          disabled={busy}
-          onClick={onAdmit}
-        >
-          <Check className="h-4 w-4" />
-          Admit
-        </Button>
-        <Button
-          variant="outline"
-          className="min-h-11 flex-1 sm:flex-none"
-          disabled={busy}
-          onClick={onDeny}
-        >
-          <X className="h-4 w-4" />
-          Deny
-        </Button>
+        {guest.actions.map((a, i) => (
+          <Button
+            key={a.kind}
+            variant={i === 0 ? "default" : "outline"}
+            className="min-h-11 flex-1 sm:flex-none"
+            disabled={busy}
+            onClick={() => onAction(a.kind)}
+          >
+            {a.kind === "admit" ? (
+              <Check className="h-4 w-4" />
+            ) : a.kind === "deny" ? (
+              <X className="h-4 w-4" />
+            ) : null}
+            {a.label}
+          </Button>
+        ))}
       </div>
     </div>
   );

package/components/ui/segmented.tsx

@@ -6,6 +6,7 @@ export interface SegmentedOption<T extends string> {
   value: T;
   label: string;
   hint?: string;
+  disabled?: boolean;
 }
 
 /** One choice out of a few, side by side. Radio semantics, 44px targets. */
@@ -37,7 +38,7 @@ export function Segmented<T extends string>({
             role="radio"
             aria-checked={on}
             title={o.hint}
-            disabled={disabled}
+            disabled={disabled || o.disabled}
             onClick={() => !on && onChange(o.value)}
             className={cn(
               "min-h-11 rounded-md px-2 text-sm font-medium transition-colors disabled:opacity-50",

package/data/live/queries.ts

@@ -1,8 +1,20 @@
 import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
-import type { LiveExpiry, LiveResponse, LiveView } from "@/lib/live/types";
+import type {
+  LiveExpiry,
+  LiveInvite,
+  LiveLevel,
+  LiveResponse,
+  LiveView,
+} from "@/lib/live/types";
 import { liveKeys } from "./keys";
 
-export type { LiveExpiry, LiveResponse, LiveView } from "@/lib/live/types";
+export type {
+  LiveExpiry,
+  LiveInvite,
+  LiveLevel,
+  LiveResponse,
+  LiveView,
+} from "@/lib/live/types";
 
 async function json<T>(res: Response): Promise<T> {
   const data = await res.json().catch(() => ({}));
@@ -31,6 +43,7 @@ export function useLiveShare(sessionId: string | undefined, enabled = true) {
     select: (r) => ({
       linked: r.linked,
       share: r.shares[0] as LiveView | undefined,
+      invite: r.invite as LiveInvite | undefined,
     }),
     refetchInterval: (q) => (q.state.data?.shares.length ? 2000 : 60_000),
   });
@@ -39,14 +52,19 @@ export function useLiveShare(sessionId: string | undefined, enabled = true) {
 export function useCreateLive() {
   const qc = useQueryClient();
   return useMutation({
-    mutationFn: async (req: { sessionId: string; expiresIn: LiveExpiry }) =>
-      json<LiveView>(await send("/api/live-shares", "POST", req)),
+    mutationFn: async (req: {
+      sessionId: string;
+      expiresIn: LiveExpiry;
+      level: LiveLevel;
+      history: boolean;
+    }) => json<LiveView>(await send("/api/live-shares", "POST", req)),
     onSuccess: () => qc.invalidateQueries({ queryKey: liveKeys.all }),
   });
 }
 
 export type LiveAction =
   | { action: "admit" | "deny" | "kick"; guestId: string }
+  | { action: "level"; level: LiveLevel }
   | { action: "send"; suggestionId: string; text?: string }
   | { action: "dismiss"; suggestionId: string };
 

package/lib/connect/control-api.ts

@@ -488,12 +488,16 @@ export interface LiveShare {
 export async function createLiveShare(
   config: ConnectConfig,
   privateKey: string,
-  share: { title: string; expiresIn: LiveExpiry }
+  share: { title: string; expiresIn: LiveExpiry; access?: string }
 ): Promise<LiveShare> {
   const res = await signed(config, privateKey)(
     "POST",
     `/api/v1/machines/${config.machineId}/live-shares`,
-    { title: share.title, expires_in: share.expiresIn }
+    {
+      title: share.title,
+      expires_in: share.expiresIn,
+      ...(share.access ? { access: share.access } : {}),
+    }
   );
   const r = (await res.json().catch(() => null)) as Record<
     string,

package/lib/db/migrations/20261030T1200_live_share_level.ts

@@ -0,0 +1,19 @@
+import type { Migration } from "../migration-types";
+
+export default {
+  key: "20261030T1200_live_share_level",
+  up: (db) => {
+    const cols = (
+      db.prepare(`PRAGMA table_info(live_shares)`).all() as { name: string }[]
+    ).map((c) => c.name);
+    // Existing links keep what they always did: suggest, with the whole chat.
+    if (!cols.includes("level"))
+      db.exec(
+        `ALTER TABLE live_shares ADD COLUMN level TEXT NOT NULL DEFAULT 'suggest'`
+      );
+    if (!cols.includes("history"))
+      db.exec(
+        `ALTER TABLE live_shares ADD COLUMN history INTEGER NOT NULL DEFAULT 1`
+      );
+  },
+} satisfies Migration;

package/lib/live/inbox.ts

@@ -27,6 +27,7 @@ export const DOWNWARD = [
   "slow_down",
   "invalid",
   "admit_failed",
+  "access_failed",
 ] as const;
 
 const id = z.string().min(1).max(64);
@@ -44,6 +45,7 @@ const SCHEMAS = {
   slow_down: z.object({}),
   invalid: z.object({}),
   admit_failed: z.object({ guest_id: id.optional(), reason: z.string() }),
+  access_failed: z.object({ reason: z.string().max(200).optional() }),
 } satisfies Record<(typeof DOWNWARD)[number], z.ZodType>;
 
 export interface InboxEffects {
@@ -143,6 +145,9 @@ export function handleFrame(
     }
     case "suggestion": {
       const s = parsed.data as z.infer<typeof SCHEMAS.suggestion>;
+      // Watch guests can't suggest. Connect refuses first; this is the machine's own check.
+      if (rt.share.level === "watch")
+        return (drop("suggestion on a watch-only share"), false);
       const known = rt.guests.get(s.guest.id);
       // Only a guest this machine let in can leave a card.
       if (!known || known.status !== "admitted")
@@ -196,6 +201,9 @@ export function handleFrame(
       rt.notice = "Your plan's guest limit is reached.";
       return true;
     }
+    case "access_failed":
+      rt.notice = "Connect refused that access level.";
+      return true;
     case "invalid":
       rt.drops++;
       return true;

package/lib/live/levels.ts

@@ -0,0 +1,29 @@
+import {
+  LEVELS,
+  type GuestAction,
+  type LevelOption,
+  type LiveLevel,
+} from "./types";
+import type { Guest, Runtime } from "./runtime";
+
+const ORDER: LiveLevel[] = ["watch", "suggest", "drive"];
+
+/** What the invite dialog and the Live popover offer, with why one is off. */
+export function levelOptions(): LevelOption[] {
+  return ORDER.map((value) => ({
+    value,
+    ...LEVELS[value],
+    ...(value === "drive"
+      ? { enabled: false, reason: "Coming soon" }
+      : { enabled: true }),
+  }));
+}
+
+export function guestActions(_rt: Runtime, g: Guest): GuestAction[] {
+  return g.status === "pending"
+    ? [
+        { kind: "admit", label: "Admit" },
+        { kind: "deny", label: "Deny" },
+      ]
+    : [{ kind: "kick", label: "Kick" }];
+}

package/lib/live/publisher.ts

@@ -13,8 +13,17 @@ import { live, type Runtime } from "./runtime";
 const FLUSH_MS = 1000;
 const SLOW_FLUSH_MS = 4000;
 
+/** With "earlier messages" off, nothing from before the link was made goes out. */
+function beforeLink(rt: Runtime, item: ChatItem): boolean {
+  return (
+    rt.share.history === 0 &&
+    (item.createdAt ?? Infinity) < Date.parse(rt.share.created_at)
+  );
+}
+
 export function seed(rt: Runtime, sessionId: string): void {
   for (const item of visible(listItems(sessionId))) {
+    if (beforeLink(rt, item)) continue;
     const frame = rt.map(item);
     if (frame) rt.ring.upsert(frame);
   }
@@ -55,6 +64,7 @@ export function onMessage(sessionId: string, m: ChatServerMessage): void {
       live.socket?.send(rt.share.id, "state", { state: stateOf(m.state) });
     } else if (m.type === "item") {
       const item = m.item;
+      if (beforeLink(rt, item)) continue;
       if (item.kind === "turn_end") {
         flush(rt);
         live.socket?.send(rt.share.id, "state", { state: "idle" });

package/lib/live/service.ts

@@ -11,12 +11,20 @@ import { shareContext } from "../share/context";
 import { redactForShare } from "../share/redact";
 import { ShareError, createLiveRemote, revokeRemote } from "../share/connect";
 import type { LiveExpiry } from "../connect/control-api";
-import type { LiveView } from "./types";
+import {
+  LEVELS,
+  type LiveInvite,
+  type LiveLevel,
+  type LiveView,
+} from "./types";
+import { guestActions, levelOptions } from "./levels";
+import { listItems } from "../chat/store";
+import { visible } from "../share/snapshot";
 import { cleanBody } from "./clean";
 import { itemMapper } from "./frames";
 import { handleFrame } from "./inbox";
 import { onMessage, seed, flush } from "./publisher";
-import { Ring } from "./ring";
+import { RING_ITEMS, Ring } from "./ring";
 import { LOBBY_MS, live, type Guest, type Runtime } from "./runtime";
 import { LiveSocket, type WsFactory } from "./socket";
 import {
@@ -27,6 +35,7 @@ import {
   logLive,
   markLiveEnded,
   openSuggestions,
+  setLevel,
   type LiveShareRow,
 } from "./store";
 
@@ -126,7 +135,9 @@ function runtimeFor(id: string): Runtime {
 
 export async function createLive(
   sessionId: string,
-  expiresIn: LiveExpiry
+  expiresIn: LiveExpiry,
+  level: LiveLevel = "suggest",
+  history = true
 ): Promise<LiveView> {
   startLive();
   const session = getSession(sessionId);
@@ -138,7 +149,7 @@ export async function createLive(
       .text.replace(/\s+/g, " ")
       .trim()
       .slice(0, 120) || "Chat";
-  const made = await createLiveRemote({ title, expiresIn });
+  const made = await createLiveRemote({ title, expiresIn, access: level });
   const row: LiveShareRow = {
     id: made.id,
     session_id: sessionId,
@@ -149,12 +160,45 @@ export async function createLive(
     created_at: new Date().toISOString(),
     expires_at: made.expires_at,
     ended_at: null,
+    level,
+    history: history ? 1 : 0,
   };
   insertLiveShare(row);
   attach(row);
   return viewOf(row.id)!;
 }
 
+export function changeLevel(id: string, level: LiveLevel): void {
+  const rt = runtimeFor(id);
+  if (!(level in LEVELS)) throw new ShareError("Unknown level.", 400);
+  if (!levelOptions().find((o) => o.value === level)?.enabled)
+    throw new ShareError(`${LEVELS[level].label} isn't available.`, 400);
+  if (rt.share.level === level) return;
+  // Synchronous and first: from here the machine treats the share as `level`.
+  rt.share = { ...rt.share, level };
+  setLevel(id, level);
+  rt.notice = null;
+  live.socket?.send(id, "access", { level });
+}
+
+/** What the invite dialog offers for a session. */
+export function inviteFor(sessionId: string): LiveInvite {
+  const count = Math.min(
+    visible(listItems(sessionId)).filter(
+      (i) => i.kind === "user" || i.kind === "assistant"
+    ).length,
+    RING_ITEMS
+  );
+  return {
+    levels: levelOptions(),
+    history: {
+      label: `Include the ${count} earlier message${count === 1 ? "" : "s"}`,
+      default: true,
+      count,
+    },
+  };
+}
+
 /** Ends access: Connect disconnects every guest, then this machine lets go. */
 export async function endLive(id: string): Promise<void> {
   runtimeFor(id);
@@ -293,6 +337,9 @@ export function viewOf(id: string, now = Date.now()): LiveView | null {
     maxGuests: rt.share.max_guests,
     connected: live.socket?.connected ?? false,
     notice: rt.notice,
+    level: rt.share.level,
+    levels: levelOptions(),
+    history: rt.share.history === 1,
     guests: shown
       .filter((g) => g.status === "pending" || admitted.has(g.id))
       .map((g) => ({
@@ -302,6 +349,7 @@ export function viewOf(id: string, now = Date.now()): LiveView | null {
         online: g.online,
         duplicateName:
           (names.get(g.name.normalize("NFKC").toLowerCase()) ?? 0) > 1,
+        actions: guestActions(rt, g),
       })),
     suggestions: openSuggestions(id),
   };

package/lib/live/store.ts

@@ -1,4 +1,5 @@
 import { db } from "../db";
+import type { LiveLevel } from "./types";
 
 export interface LiveShareRow {
   id: string;
@@ -10,6 +11,9 @@ export interface LiveShareRow {
   created_at: string;
   expires_at: string | null;
   ended_at: string | null;
+  level: LiveLevel;
+  /** 1: guests get the chat from before the link was made. */
+  history: number;
 }
 
 export type LogKind =
@@ -19,7 +23,8 @@ export type LogKind =
   | "kick"
   | "suggestion"
   | "sent"
-  | "dismissed";
+  | "dismissed"
+  | "level";
 
 export interface LogRow {
   id: number;
@@ -36,8 +41,8 @@ export interface LogRow {
 export function insertLiveShare(row: LiveShareRow): void {
   db.prepare(
     `INSERT INTO live_shares
-       (id, session_id, title, url, ends_with_session, max_guests, created_at, expires_at, ended_at)
-     VALUES (@id, @session_id, @title, @url, @ends_with_session, @max_guests, @created_at, @expires_at, @ended_at)`
+       (id, session_id, title, url, ends_with_session, max_guests, created_at, expires_at, ended_at, level, history)
+     VALUES (@id, @session_id, @title, @url, @ends_with_session, @max_guests, @created_at, @expires_at, @ended_at, @level, @history)`
   ).run(row);
 }
 
@@ -70,6 +75,19 @@ export function markLiveEnded(id: string): void {
   ).run(new Date().toISOString(), id);
 }
 
+export function setLevel(id: string, level: LiveLevel): void {
+  db.prepare(`UPDATE live_shares SET level = ? WHERE id = ?`).run(level, id);
+  logLive({
+    share_id: id,
+    kind: "level",
+    guest_id: null,
+    guest_name: null,
+    ref: level,
+    text: null,
+    sent_text: null,
+  });
+}
+
 export function logLive(
   row: Omit<LogRow, "id" | "at"> & { at?: number }
 ): void {

package/lib/live/types.ts

@@ -1,3 +1,34 @@
+export type LiveLevel = "watch" | "suggest" | "drive";
+
+/** The single source for what each level is called and what it lets a guest do. */
+export const LEVELS: Record<LiveLevel, { label: string; hint: string }> = {
+  watch: {
+    label: "Watch",
+    hint: "Guests only watch. They can't send you anything.",
+  },
+  suggest: {
+    label: "Suggest",
+    hint: "Guests can suggest a prompt. Nothing reaches the agent unless you tap Send.",
+  },
+  drive: {
+    label: "Drive",
+    hint: "Guests can make the agent read this task's files. Everything else waits for you.",
+  },
+};
+
+export interface LevelOption {
+  value: LiveLevel;
+  label: string;
+  hint: string;
+  enabled: boolean;
+  reason?: string;
+}
+
+export interface GuestAction {
+  kind: "kick" | "admit" | "deny";
+  label: string;
+}
+
 // What the host's screens show of a live share (served by /api/live-shares).
 export interface LiveView {
   id: string;
@@ -9,6 +40,10 @@ export interface LiveView {
   maxGuests: number;
   connected: boolean;
   notice: string | null;
+  level: LiveLevel;
+  levels: LevelOption[];
+  /** Whether the guests got the chat from before the link was made. */
+  history: boolean;
   guests: {
     id: string;
     name: string;
@@ -16,6 +51,7 @@ export interface LiveView {
     online: boolean;
     /** Another guest here has the same name. */
     duplicateName: boolean;
+    actions: GuestAction[];
   }[];
   suggestions: {
     id: string;
@@ -33,7 +69,14 @@ export const EXPIRY_LABEL: Record<LiveExpiry, string> = {
   session: "Until the session ends",
 };
 
+export interface LiveInvite {
+  levels: LevelOption[];
+  history: { label: string; default: boolean; count: number };
+}
+
 export interface LiveResponse {
   linked: boolean;
   shares: LiveView[];
+  /** Only when the request named a session. */
+  invite?: LiveInvite;
 }

package/lib/orchestrator/describe.ts

@@ -64,15 +64,35 @@ function sessionLine(f: SessionFacts): string {
   return parts.join(" | ");
 }
 
-// The sessions tool's answer: one line per session, busiest news first.
+const compactLine = (f: SessionFacts) =>
+  `${f.name} (${f.project ?? "no project"}, id ${shortId(f.id)})`;
+
+// Nothing to say about it beyond that it is idle.
+const plainIdle = (f: SessionFacts) =>
+  f.status === "idle" &&
+  !f.activity &&
+  !f.task &&
+  !f.plan &&
+  !f.group &&
+  !f.stack &&
+  !f.compacting &&
+  !f.waits?.on.length &&
+  !f.waits?.by.length;
+
+// The sessions tool's answer: one line per live session, busiest news first;
+// then the done and plain idle ones, compactly, so a done can be seen to have
+// worked.
 export function describeSessions(
   workspace: string,
   facts: SessionFacts[],
   groups: readonly string[] = []
 ): string {
   if (!facts.length) return `No sessions are running in ${workspace}.`;
+  const done = facts.filter((f) => f.done && f.status !== "running");
+  const idle = facts.filter((f) => !f.done && plainIdle(f));
+  const shown = facts.filter((f) => !done.includes(f) && !idle.includes(f));
   const rank = { waiting: 0, running: 1, idle: 2, dead: 3 };
-  const sorted = [...facts].sort((a, b) => rank[a.status] - rank[b.status]);
+  const sorted = [...shown].sort((a, b) => rank[a.status] - rank[b.status]);
   const counts = (["running", "waiting"] as const)
     .map((s) => {
       const n = facts.filter((f) => f.status === s).length;
@@ -84,6 +104,10 @@ export function describeSessions(
   return [
     `${facts.length} ${noun} in ${workspace}${summary}:`,
     ...sorted.map(sessionLine),
+    ...(idle.length ? [`Idle: ${idle.map(compactLine).join("; ")}.`] : []),
+    ...(done.length
+      ? [`Done (on Saad's Done shelf): ${done.map(compactLine).join("; ")}.`]
+      : []),
     ...(groups.length
       ? [`Saad's groups here: ${groups.map((g) => `"${g}"`).join(", ")}.`]
       : []),

package/lib/orchestrator/facts.ts

@@ -27,6 +27,7 @@ import { commitTime, repoOf } from "./repo";
 import { CHECKLESS_MS, checklessFor, ciSettleIn } from "./task-state";
 import { repoHasCI } from "./repo-ci";
 import { markStatusDirty } from "../status/dirty";
+import { settledHow } from "../sidebar/shelves";
 
 export type FactStatus = "running" | "waiting" | "idle" | "dead";
 
@@ -46,6 +47,8 @@ export interface SessionFacts {
   compacting?: boolean;
   // Saad's group it sits in, when it is in one.
   group?: string | null;
+  // On Saad's Done shelf: marked done (or quiet for days) and not woken since.
+  done?: boolean;
   // Last sign of life, in ms.
   lastActive: number;
   // Open waits (aos send --await, aos wait): who it waits on, and who waits on it.
@@ -346,6 +349,7 @@ export async function sessionFacts(
         compacting:
           s.view === "chat" && !hostLink(s.host_id) && !!chatCompacting(s.id),
         group: groups.get(s.session_group_id ?? "") ?? null,
+        done: settledHow(s, Date.now()) !== null,
         lastActive: await lastActiveFor(s),
         branch: s.branch_name,
         quick: !!s.quick_of,

package/lib/orchestrator/tools.ts

@@ -116,7 +116,7 @@ const answer = async (call: Promise<string>): Promise<CallToolResult> => {
 
 const DESCRIPTIONS: Record<ToolName, string> = {
   sessions:
-    "Every session in this workspace: project, view, status, what it's doing, task/PR/CI state and stack position; then external sessions (tmux sessions AgentOS didn't start, here or on other machines, working in a workspace repository), read-only, with their branch's PR.",
+    "Every session in this workspace: project, view, status, what it's doing, task/PR/CI state and stack position; plain idle and done sessions (on Saad's Done shelf) are listed compactly after them; then external sessions (tmux sessions AgentOS didn't start, here or on other machines, working in a workspace repository), read-only, with their branch's PR.",
   read: "The end of one session's terminal or chat, or an external session's screen, as plain text (capped at about 4k tokens).",
   cards: "Cards on this workspace's linked LumifyHub boards, by list.",
   logs: "Session logs AgentOS wrote when tasks merged: the last N headers (task, PR, cost, duration) of the workspace or one project, or one log in full (brief, plan, timeline, usage, outcome). Read straight from the database; nothing is summarised.",

package/lib/program-status/store.ts

@@ -85,7 +85,8 @@ function commit(sessionName: string, next: Records): boolean {
   if (same(before, after)) return false;
   if (after && after.state !== "idle" && after.state !== before?.state)
     db.prepare(
-      `UPDATE sessions SET updated_at = datetime('now'), active_at = datetime('now') WHERE tmux_name = ? OR id = ?`
+      `UPDATE sessions SET updated_at = datetime('now'), active_at = datetime('now') WHERE (tmux_name = ? OR id = ?)
+         AND (settled_at IS NULL OR active_at > settled_at)`
     ).run(sessionName, getSessionIdFromName(sessionName));
   return true;
 }

package/lib/session-activity.ts

@@ -1,7 +1,9 @@
 import { getDb } from "./db";
 
 // A session did something: a message, a run starting, a need. Written at most
-// once a minute, unless it wakes a snooze or brings a settled session back.
+// once a minute, unless it wakes a snooze. Never for a settled session: what
+// comes after Done (the stop's own events, a status refresh) isn't the work
+// starting again. Only a prompt does that (the chat worker writes it).
 export function touchActive(sessionId: string): void {
   try {
     getDb()
@@ -9,8 +11,8 @@ export function touchActive(sessionId: string): void {
         `UPDATE sessions SET active_at = datetime('now')
          WHERE id = ? AND (active_at IS NULL
            OR active_at < datetime('now', '-60 seconds')
-           OR (snoozed_at IS NOT NULL AND active_at <= snoozed_at)
-           OR (settled_at IS NOT NULL AND active_at <= settled_at))`
+           OR (snoozed_at IS NOT NULL AND active_at <= snoozed_at))
+           AND (settled_at IS NULL OR active_at > settled_at)`
       )
       .run(sessionId);
   } catch (err) {

package/lib/share/connect.ts

@@ -111,6 +111,7 @@ export async function revokeRemote(id: string): Promise<void> {
 export async function createLiveRemote(share: {
   title: string;
   expiresIn: LiveExpiry;
+  access?: string;
 }) {
   const { config, machineKey } = files();
   try {

package/lib/sidebar/shelves.ts

@@ -220,7 +220,10 @@ export function settledHow(
   now: number
 ): "manual" | "auto" | null {
   const active = activeMs(session, now);
-  if (session.settled_at && active <= ms(session.settled_at)) return "manual";
+  // A settled session's own row is the clock: updated_at moves with
+  // bookkeeping, so it never takes a done session off the shelf.
+  const own = session.peer_mirror || session.active_at ? active : 0;
+  if (session.settled_at && own <= ms(session.settled_at)) return "manual";
   return now - active >= SETTLE_AFTER_MS ? "auto" : null;
 }
 

package/lib/status/collect.ts

@@ -421,7 +421,8 @@ async function collect(full = false): Promise<StatusSnapshot> {
 
   // Batch update sessions and claude_session_id in a single transaction
   const updateStatusStmt = db.prepare(
-    "UPDATE sessions SET updated_at = datetime('now'), active_at = datetime('now') WHERE id = ?"
+    `UPDATE sessions SET updated_at = datetime('now'), active_at = datetime('now')
+     WHERE id = ? AND (settled_at IS NULL OR active_at > settled_at)`
   );
   const updateClaudeIdStmt = db.prepare(
     "UPDATE sessions SET claude_session_id = ? WHERE id = ? AND (claude_session_id IS NULL OR claude_session_id != ?)"

package/package.json

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