@saadnvd1/agent-os 0.3.778 → 0.3.780

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,21 @@ 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: "admit"; guestId: string; drive?: boolean }
+  | { action: "deny" | "kick"; guestId: string }
+  | { action: "wheel"; guestId: string | null }
+  | { action: "level"; level: LiveLevel }
   | { action: "send"; suggestionId: string; text?: string }
   | { action: "dismiss"; suggestionId: string };
 

package/lib/chat/driver.ts

@@ -2,6 +2,7 @@ import type {
   McpServerConfig,
   PermissionMode,
 } from "@anthropic-ai/claude-agent-sdk";
+import type { GuestGate } from "./worker/guest-gate";
 import type {
   ApprovalDecision,
   ChatAccess,
@@ -60,6 +61,9 @@ export interface ChatStartOptions {
   // refused, null to let it go on to them, or a warning the agent is shown
   // while the call still goes on.
   toolGuard?: ToolGuard;
+  // Holds a live guest's turn to the host's taps (./worker/guest-gate). A
+  // driver without it can't take Drive prompts (the worker's caps say so).
+  guestGate?: GuestGate;
   // The note handed back to the agent right after its context is compacted
   // (lib/chat/compact-context), empty for none. Only Claude Code has a hook
   // for it; other drivers ignore it.

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

@@ -15,6 +15,7 @@ import type {
 } from "../events";
 import { toolDiff, toolTitle } from "../tools";
 import type { ToolGuard } from "../driver";
+import { guestGateHook, type GuestGate } from "../worker/guest-gate";
 
 type Approval = Extract<ChatItem, { kind: "approval" }>;
 
@@ -101,45 +102,94 @@ export class Approvals {
     private planFile: () => string | undefined = () => undefined
   ) {}
 
+  // Who steers the running turn, when a live guest does (lib/chat/worker/
+  // guest-gate): every card it raises is theirs, with no Always.
+  guestOf: () => { name: string } | null = () => null;
+  // Calls the guest gate let through, by tool use id: the permission prompt
+  // that may follow for one is already answered.
+  private gatePassed = new Set<string>();
+
   canUseTool: CanUseTool = (toolName, input, options) => {
     // Already answered on its card by the question hook.
     if (toolName === "AskUserQuestion" && "answers" in input)
       return Promise.resolve({ behavior: "allow", updatedInput: input });
+    if (options.toolUseID && this.gatePassed.delete(options.toolUseID))
+      return Promise.resolve({ behavior: "allow", updatedInput: input });
     const questions =
       toolName === "AskUserQuestion"
         ? ((input as { questions?: ChatQuestion[] }).questions ?? [])
         : undefined;
-    const item: Approval = {
-      id: `approval-${options.toolUseID}`,
-      kind: "approval",
-      toolName,
-      title: options.title ?? toolTitle(toolName, input),
-      input,
-      diff: toolDiff(toolName, input),
-      questions,
-      canAlways:
-        !questions &&
-        !!options.suggestions?.length &&
-        !options.suppressAlwaysAllowRule,
-      status: "pending",
-      createdAt: Date.now(),
-    };
+    const guest = this.guestOf() ?? undefined;
+    return this.ask(
+      {
+        id: `approval-${options.toolUseID}`,
+        kind: "approval",
+        toolName,
+        title: options.title ?? toolTitle(toolName, input),
+        input,
+        diff: toolDiff(toolName, input),
+        questions,
+        canAlways:
+          !guest &&
+          !questions &&
+          !!options.suggestions?.length &&
+          !options.suppressAlwaysAllowRule,
+        status: "pending",
+        createdAt: Date.now(),
+        ...(guest && { guest }),
+      },
+      options.signal,
+      guest ? undefined : options.suggestions
+    );
+  };
+
+  // A step of a guest-steered turn: the host's card, never Always.
+  askGuest(
+    toolName: string,
+    input: Record<string, unknown>,
+    toolUseID: string,
+    signal: AbortSignal,
+    guest: { name: string }
+  ): Promise<PermissionResult> {
+    return this.ask(
+      {
+        id: `approval-${toolUseID}`,
+        kind: "approval",
+        toolName,
+        title: toolTitle(toolName, input),
+        input,
+        diff: toolDiff(toolName, input),
+        canAlways: false,
+        status: "pending",
+        createdAt: Date.now(),
+        guest,
+      },
+      signal
+    );
+  }
+
+  passed(toolUseID: string): void {
+    if (toolUseID) this.gatePassed.add(toolUseID);
+  }
+
+  private ask(
+    item: Approval,
+    signal: AbortSignal,
+    suggestions?: Parameters<CanUseTool>[2]["suggestions"]
+  ): Promise<PermissionResult> {
     return new Promise<PermissionResult>((resolve) => {
-      this.pending.set(item.id, {
-        item,
-        suggestions: options.suggestions,
-        resolve,
-      });
-      options.signal.addEventListener("abort", () => {
+      this.pending.set(item.id, { item, suggestions, resolve });
+      const expire = () =>
         this.settle(item.id, "expired", {
           behavior: "deny",
           message: DENIED,
         });
-      });
+      if (signal.aborted) return queueMicrotask(expire);
+      signal.addEventListener("abort", expire);
       this.emit({ type: "item", item });
       this.emit({ type: "state", state: "waiting" });
     });
-  };
+  }
 
   // Full access approves every tool before canUseTool is asked, questions
   // included, so the agent's questions come through this hook instead.
@@ -209,11 +259,14 @@ export class Approvals {
     } else if (answer.decision === "deny") {
       this.settle(id, "denied", { behavior: "deny", message: DENIED });
     } else {
+      // A guest's card has no Always: an "always" answer is a plain allow.
       this.settle(id, "allowed", {
         behavior: "allow",
         updatedInput: input,
         updatedPermissions:
-          answer.decision === "always" ? p.suggestions : undefined,
+          answer.decision === "always" && !p.item.guest
+            ? p.suggestions
+            : undefined,
       });
     }
   }
@@ -270,9 +323,24 @@ export function guardHook(guard: ToolGuard): HookCallback {
 export function preToolUseHooks(
   approvals: Approvals,
   guard?: ToolGuard,
-  subagentModels?: HookCallback | null
+  subagentModels?: HookCallback | null,
+  // A live guest's turn: every call but a worktree read waits for the host.
+  guest?: { gate: GuestGate; cwd: string }
 ): HookCallbackMatcher[] {
+  if (guest)
+    approvals.guestOf = () =>
+      guest.gate.steer ? { name: guest.gate.steer.name } : null;
   return [
+    // First, and on every tool: no steer, no effect. It waits on the host
+    // for as long as the card is up (the turn's own cap ends it sooner).
+    ...(guest
+      ? [
+          {
+            hooks: [guestGateHook(approvals, guest.gate, guest.cwd)],
+            timeout: 24 * 60 * 60,
+          },
+        ]
+      : []),
     // Sets the model of a subagent call by its type. It only fills in the
     // input, so the guard and permissions below still see the call.
     ...(subagentModels

package/lib/chat/drivers/claude.ts

@@ -222,7 +222,8 @@ export const claudeDriver: ChatDriver = {
           PreToolUse: preToolUseHooks(
             approvals,
             options.toolGuard,
-            subagentHook(options.env)
+            subagentHook(options.env),
+            options.guestGate && { gate: options.guestGate, cwd: options.cwd }
           ),
           ...(options.compactContext && {
             SessionStart: compactedHooks(options.compactContext),

package/lib/chat/events.ts

@@ -84,7 +84,12 @@ export type ChatOriginKind =
   | "device"
   // A suggestion from a guest on a live link, sent by the reader after
   // reading it. Its label is the guest's name.
-  | "guest";
+  | "guest"
+  // A prompt from the guest holding the wheel on a Drive live link: it went
+  // in without the host's tap, so every step it takes past reading the
+  // task's files waits for one (lib/chat/worker/guest-gate). Its body is
+  // the guest's own text; the agent got it framed as a stranger's.
+  | "guest-drive";
 
 export interface ChatOrigin {
   kind: ChatOriginKind;
@@ -102,6 +107,11 @@ export interface ChatOrigin {
   // Only Away mode's own lines: the turn it starts isn't anyone's activity
   // (lib/away/activity).
   away?: true;
+  // A guest-drive message: the live share, the guest it came from, and the
+  // wheel it was sent under (a new one each time the host gives it).
+  share?: string;
+  guestId?: string;
+  wheel?: string;
 }
 
 // Who sent a message, carried with it through the queue and the worker.
@@ -109,6 +119,10 @@ export interface SentBy {
   from?: string;
   peer?: PeerMessage;
   origin?: ChatOrigin;
+  // The host sent it themselves: set only by their own composer and taps
+  // (never by an agent, event or schedule). Only such a message ends a live
+  // guest's steer (lib/chat/worker/guest-gate).
+  host?: true;
 }
 
 export interface McpServerView {
@@ -285,6 +299,9 @@ export type ChatItem =
       status: "pending" | "allowed" | "denied" | "answered" | "expired";
       // Allowed by No approvals mode, not by the reader.
       auto?: boolean;
+      // Asked in a turn a live guest steered: only the reader's tap answers
+      // it (never No approvals mode), and it has no Always.
+      guest?: { name: string };
     })
   | (Base & {
       // Work the agent runs alongside the turn: a background shell, a
@@ -323,6 +340,9 @@ export interface QueuedMessage {
   imageCount?: number;
   fileCount?: number;
   createdAt: number;
+  // A live guest's Drive prompt: who it's from and what they typed (the
+  // text is what the agent gets, framed).
+  guest?: { name: string; body: string };
 }
 
 // A file or folder the agent would match for an @mention.

package/lib/chat/queued.ts

@@ -26,7 +26,7 @@ export function listQueue(sessionId: string): QueuedMessage[] {
   return (
     db
       .prepare(
-        `SELECT id, text, image_count, files, created_at
+        `SELECT id, text, image_count, files, sent_by, created_at
          FROM chat_queue WHERE session_id = ? ORDER BY position, created_at`
       )
       .all(sessionId) as {
@@ -34,15 +34,57 @@ export function listQueue(sessionId: string): QueuedMessage[] {
       text: string;
       image_count: number;
       files: string | null;
+      sent_by: string | null;
       created_at: number;
     }[]
-  ).map((r) => ({
-    id: r.id,
-    text: r.text,
-    imageCount: r.image_count || undefined,
-    fileCount: r.files ? (JSON.parse(r.files) as unknown[]).length : undefined,
-    createdAt: r.created_at,
-  }));
+  ).map((r) => {
+    const o = r.sent_by ? (JSON.parse(r.sent_by) as SentBy).origin : undefined;
+    return {
+      id: r.id,
+      text: r.text,
+      imageCount: r.image_count || undefined,
+      fileCount: r.files
+        ? (JSON.parse(r.files) as unknown[]).length
+        : undefined,
+      createdAt: r.created_at,
+      ...(o?.kind === "guest-drive"
+        ? { guest: { name: o.label, body: o.body ?? r.text } }
+        : {}),
+    };
+  });
+}
+
+// Who sent the message that goes next, without taking it.
+export function peekNextSentBy(sessionId: string): SentBy | null {
+  const row = db
+    .prepare(
+      `SELECT sent_by FROM chat_queue WHERE session_id = ? ORDER BY position, created_at LIMIT 1`
+    )
+    .get(sessionId) as { sent_by: string | null } | undefined;
+  if (!row) return null;
+  return row.sent_by ? (JSON.parse(row.sent_by) as SentBy) : {};
+}
+
+// Drops every queued message whose sender matches; returns the ids dropped.
+export function deleteQueuedWhere(
+  sessionId: string,
+  match: (by: SentBy) => boolean
+): string[] {
+  return db.transaction(() => {
+    const rows = db
+      .prepare(
+        `SELECT id, sent_by FROM chat_queue WHERE session_id = ? AND sent_by IS NOT NULL`
+      )
+      .all(sessionId) as { id: string; sent_by: string }[];
+    const ids = rows
+      .filter((r) => match(JSON.parse(r.sent_by) as SentBy))
+      .map((r) => r.id);
+    const del = db.prepare(
+      `DELETE FROM chat_queue WHERE session_id = ? AND id = ?`
+    );
+    for (const id of ids) del.run(sessionId, id);
+    return ids;
+  })();
 }
 
 // At the back. A retried send with the same id is only queued once.
@@ -56,7 +98,12 @@ export function enqueue(
   } & SentBy
 ): void {
   const images = m.images?.length ? JSON.stringify(m.images) : null;
-  const sentBy: SentBy = { from: m.from, peer: m.peer, origin: m.origin };
+  const sentBy: SentBy = {
+    from: m.from,
+    peer: m.peer,
+    origin: m.origin,
+    host: m.host,
+  };
   if (m.text.length > MAX_QUEUED_TEXT)
     throw new Error("That message is too long to queue");
   if (images && images.length > MAX_QUEUED_IMAGES)
@@ -77,7 +124,7 @@ export function enqueue(
     images,
     m.images?.length ?? 0,
     m.files?.length ? JSON.stringify(m.files) : null,
-    m.from || m.peer || m.origin ? JSON.stringify(sentBy) : null,
+    m.from || m.peer || m.origin || m.host ? JSON.stringify(sentBy) : null,
     Date.now()
   );
 }

package/lib/chat/registry.ts

@@ -45,6 +45,8 @@ export interface Live {
   canBackground?: boolean;
   // Whether it takes "mcp_auth" (sign in to an MCP server).
   canMcpAuth?: boolean;
+  // Whether it holds a live guest's turns to the host's taps (Drive).
+  canGuestGate?: 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

@@ -21,6 +21,7 @@ import type {
   ApprovalDecision,
   ChatFile,
   ChatImage,
+  ChatOrigin,
   ChatServerMessage,
   ChatState,
   Compacting,
@@ -47,6 +48,7 @@ import {
 import { noteToolResult } from "../health/env/recordHit";
 import {
   deleteQueued,
+  deleteQueuedWhere,
   editQueued,
   enqueue,
   listQueue,
@@ -78,7 +80,7 @@ import {
   waitForExit,
 } from "./worker/client";
 import { buildId, isStaleWorker } from "../build";
-import type { WorkerEvent } from "./worker/protocol";
+import { GUEST_GATE_CAP, type WorkerEvent } from "./worker/protocol";
 import type { WorkerClient } from "./worker/client";
 import { DEMO_REFUSAL, demoMode } from "../security/demo";
 import { chatHold, chatRefusal } from "./hold";
@@ -118,6 +120,7 @@ export async function carryOutPlan(
       id: `user-carry-${planId}`,
       text: CARRY_OUT,
       origin: { kind: "decision", label: "Saad" },
+      host: true,
     },
     timeoutMs
   );
@@ -348,6 +351,7 @@ async function ensureLive(sessionId: string, spawn = true): Promise<Live> {
       canFresh: !!hello.caps?.includes("fresh"),
       canBackground: !!hello.caps?.includes("background"),
       canMcpAuth: !!hello.caps?.includes("mcp_auth"),
+      canGuestGate: !!hello.caps?.includes(GUEST_GATE_CAP),
     };
     // 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
@@ -402,10 +406,11 @@ function queuedIfHeld(
   return true;
 }
 
-const sentBy = ({ from, peer, origin }: SentBy): SentBy => ({
+const sentBy = ({ from, peer, origin, host }: SentBy): SentBy => ({
   from,
   peer,
   origin,
+  host,
 });
 
 // Already a message in the chat or its queue.
@@ -460,6 +465,64 @@ export async function sendChat(
   });
 }
 
+export const GATE_MISSING = "Reopen this chat on the host to let guests drive";
+
+/**
+ * A live guest's Drive prompt (lib/live/drive): always its own turn, behind
+ * anything running. `check` runs again right before the worker gets it, in
+ * the same tick, so a Drive that ended meanwhile sends nothing. Returns why
+ * it wasn't sent, or null.
+ */
+export async function sendGuestPrompt(
+  sessionId: string,
+  m: { id: string; text: string; origin: ChatOrigin },
+  check: () => string | null
+): Promise<string | null> {
+  const held = () =>
+    chatRefusal(sessionId) ??
+    chatHold(sessionId) ??
+    (settingUp(sessionId) || launchPending(sessionId)
+      ? "The task isn't running yet"
+      : null);
+  if (held()) return held();
+  const live = await ensureLive(sessionId);
+  if (!live.canGuestGate) return GATE_MISSING;
+  const why = held() ?? check();
+  if (why) return why;
+  if (taken(sessionId, m.id)) return "Already sent";
+  live.worker.command({ type: "send", ...m, queue: true });
+  return null;
+}
+
+// A live share's Drive ended: its queued prompts go here and in the worker
+// (which also stops a turn it steers and refuses that wheel from now on).
+export function releaseGuestChat(
+  sessionId: string,
+  share: string,
+  wheel: string
+): void {
+  const gone = deleteQueuedWhere(
+    sessionId,
+    (by) => by.origin?.kind === "guest-drive" && by.origin.share === share
+  );
+  if (gone.length) emitQueue(sessionId);
+  registry.live
+    .get(sessionId)
+    ?.worker.command({ type: "guest_release", share, wheel });
+}
+
+// The driving guest's Stop: the worker ends the turn only if their wheel
+// steers it.
+export function stopGuestTurn(
+  sessionId: string,
+  share: string,
+  wheel: string
+): void {
+  registry.live
+    .get(sessionId)
+    ?.worker.command({ type: "guest_stop", share, wheel });
+}
+
 // The queue lives in SQLite, so it can be changed with no worker running;
 // a worker reads it only when it sends the next message.
 export function editQueuedChat(sessionId: string, id: string, text: string) {

package/lib/chat/socket.ts

@@ -150,15 +150,18 @@ function onChatMessage(
     const id = send.id;
     // Taken in now: a new worker can take seconds to start.
     if (id) reply({ type: "accepted", id });
-    void sendChat(sessionId, { ...send, queue: true }).catch((err) => {
-      if (id)
-        reply({
-          type: "send_failed",
-          id,
-          message: err instanceof Error ? err.message : String(err),
-        });
-      fail(err);
-    });
+    // Typed in the host's own composer (this socket is theirs).
+    void sendChat(sessionId, { ...send, queue: true, host: true }).catch(
+      (err) => {
+        if (id)
+          reply({
+            type: "send_failed",
+            id,
+            message: err instanceof Error ? err.message : String(err),
+          });
+        fail(err);
+      }
+    );
     // "Session 4" is named after its first message.
     run(titleChatFromMessage(sessionId, send.text));
   } else if (msg.type === "queue_edit" && typeof msg.text === "string")