@saadnvd1/agent-os 0.3.779 → 0.3.781

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")

package/lib/chat/worker/gate-testing.ts

@@ -0,0 +1,131 @@
+/**
+ * For tests: a real chat worker (ChatHost) over a fake agent, with the guest
+ * gate's PreToolUse hook driven as the SDK would and real approval cards.
+ * A test file mocks the drivers with this module's `drivers`:
+ *   vi.mock("@/lib/chat/drivers", async () => (await import("@/lib/chat/worker/gate-testing")).drivers)
+ */
+
+import { randomUUID } from "crypto";
+import { vi } from "vitest";
+import type { HookJSONOutput } from "@anthropic-ai/claude-agent-sdk";
+import type { Session } from "@/lib/db";
+import type { ChatConversation, ChatStartOptions } from "../driver";
+import type { ChatItem, DriverEvent } from "../events";
+import { InputQueue } from "../queue";
+import { Approvals, preToolUseHooks } from "../drivers/claude-approvals";
+import type { WorkerEvent } from "./protocol";
+
+export function fakeConversation() {
+  const events = new InputQueue<DriverEvent>();
+  return {
+    send: vi.fn(() => "checkpoint-1"),
+    runLocal: vi.fn(() => null),
+    interrupt: vi.fn(async () => {}),
+    setModel: vi.fn(async () => {}),
+    setAccess: vi.fn(async () => {}),
+    setPlan: vi.fn(async () => {}),
+    respond: vi.fn(),
+    stopTask: vi.fn(async () => {}),
+    backgroundTask: vi.fn(async () => true),
+    undo: vi.fn(),
+    close: vi.fn(() => events.end()),
+    events,
+  } satisfies ChatConversation;
+}
+
+const fake: {
+  current?: ReturnType<typeof fakeConversation>;
+  started?: ChatStartOptions;
+} = {};
+
+export const drivers = {
+  chatDriverFor: () => ({
+    id: "fake",
+    atRest: true,
+    start: (options: ChatStartOptions) => {
+      fake.started = options;
+      return fake.current!;
+    },
+  }),
+};
+
+export const tick = () => new Promise((r) => setTimeout(r, 0));
+
+// The host is imported late: it imports the drivers, which this module mocks.
+export async function gatedHost(
+  session: Session,
+  cwd: string,
+  onEvent: (e: WorkerEvent) => void = () => {}
+) {
+  const { ChatHost } = await import("./host");
+  fake.current = fakeConversation();
+  const conversation = fake.current;
+  const emitted: ChatItem[] = [];
+  const host = new ChatHost(session, (e) => {
+    if (e.type === "item") emitted.push(e.item);
+    onEvent(e);
+  });
+  const approvals = new Approvals((e) => conversation.events.push(e));
+  conversation.respond.mockImplementation((cardId, answer) =>
+    approvals.respond(cardId, answer)
+  );
+  const gate = fake.started!.guestGate!;
+  const [first] = preToolUseHooks(approvals, undefined, null, { gate, cwd });
+  const hook = first.hooks[0];
+  const results = new Map<string, HookJSONOutput>();
+  const call = (tool: string, input: Record<string, unknown>) => {
+    const useId = `tu-${randomUUID().slice(0, 8)}`;
+    const ac = new AbortController();
+    void hook(
+      {
+        hook_event_name: "PreToolUse",
+        tool_name: tool,
+        tool_input: input,
+        tool_use_id: useId,
+        session_id: "x",
+        transcript_path: "",
+        cwd,
+      } as never,
+      useId,
+      { signal: ac.signal }
+    ).then((r) => results.set(useId, r));
+    return { useId, abort: () => ac.abort() };
+  };
+  /** allow, deny, none (no decision), or pending (still waiting on the host). */
+  const decision = async (useId: string) => {
+    try {
+      await gate.placedFiles(cwd);
+    } catch {
+      // A test that makes it throw.
+    }
+    await tick();
+    await tick();
+    const r = results.get(useId) as
+      { hookSpecificOutput?: { permissionDecision?: string } } | undefined;
+    return (
+      r?.hookSpecificOutput?.permissionDecision ?? (r ? "none" : "pending")
+    );
+  };
+  const card = (useId: string) =>
+    emitted
+      .filter(
+        (i): i is Extract<ChatItem, { kind: "approval" }> =>
+          i.kind === "approval" && i.id === `approval-${useId}`
+      )
+      .at(-1);
+  const idle = async () => {
+    conversation.events.push({ type: "state", state: "idle" });
+    await tick();
+  };
+  return {
+    host,
+    gate,
+    approvals,
+    conversation,
+    call,
+    decision,
+    card,
+    idle,
+    emitted,
+  };
+}