@saadnvd1/agent-os 0.3.779 → 0.3.780

package/lib/live/runtime.ts

@@ -15,6 +15,25 @@ export interface Guest {
   at: number;
 }
 
+/** A Drive prompt this machine took and hasn't seen finish. */
+export interface DrivePrompt {
+  id: string;
+  guestId: string;
+  // sending: on its way to the worker; queued: behind a turn; running.
+  status: "sending" | "queued" | "running";
+  // Why its turn was stopped, when it was (the guest's Stop, a cap).
+  stopWhy?: string;
+}
+
+export interface DriveState {
+  wheel: { guestId: string; wheel: string } | null;
+  prompts: DrivePrompt[];
+  // When prompts were taken, for the rate caps.
+  accepted: number[];
+  // Bumped whenever a Drive ends, so a send still on its way sends nothing.
+  epoch: number;
+}
+
 /** What one live share holds in memory; everything durable is in the log. */
 export interface Runtime {
   share: LiveShareRow;
@@ -30,6 +49,7 @@ export interface Runtime {
   slowUntil: number;
   notice: string | null;
   drops: number;
+  drive: DriveState;
 }
 
 export interface LiveGlobals {

package/lib/live/service.ts

@@ -1,7 +1,8 @@
 /**
  * Live shares from the host's side: mint, run, decide on guests, end.
  * Nothing a guest sends reaches an agent except through sendSuggestion,
- * which the host taps.
+ * which the host taps, and a Drive prompt from the guest the host gave the
+ * wheel (./drive), whose turn the worker's guest gate holds to the host's taps.
  */
 
 import { loadConnect } from "../connect/config";
@@ -17,10 +18,19 @@ import {
   type LiveLevel,
   type LiveView,
 } from "./types";
-import { guestActions, levelOptions } from "./levels";
+import { driveView, guestActions, levelOptions } from "./levels";
+import {
+  driveRefusal,
+  newDrive,
+  onDriveMessage,
+  releaseDrive,
+  setWheel,
+  type DriveFx,
+} from "./drive";
+import type { Session } from "../db";
 import { listItems } from "../chat/store";
 import { visible } from "../share/snapshot";
-import { cleanBody } from "./clean";
+import { cleanBody, noMentions } from "./clean";
 import { itemMapper } from "./frames";
 import { handleFrame } from "./inbox";
 import { onMessage, seed, flush } from "./publisher";
@@ -63,6 +73,18 @@ export function makeSocket(factory?: WsFactory): LiveSocket {
 
 const socket = (): LiveSocket => (live.socket ??= makeSocket());
 
+const fx: DriveFx = {
+  send: (id, action, data) => live.socket?.send(id, action, data),
+};
+
+const sessionOrNull = (id: string): Session | null => {
+  try {
+    return getSession(id);
+  } catch {
+    return null;
+  }
+};
+
 function stateOfSession(sessionId: string) {
   const l = registry.live.get(sessionId);
   const s = l?.state;
@@ -87,6 +109,7 @@ function attach(row: LiveShareRow): Runtime {
     slowUntil: 0,
     notice: null,
     drops: 0,
+    drive: newDrive(row.id),
   };
   live.runtimes.set(row.id, rt);
   try {
@@ -99,6 +122,7 @@ function attach(row: LiveShareRow): Runtime {
 /** Stops publishing a share and drops its connection; the row stays as history. */
 function stop(shareId: string, markEnded = false): void {
   const rt = live.runtimes.get(shareId);
+  if (rt) releaseDrive(rt, "ended", fx);
   if (markEnded) markLiveEnded(shareId);
   if (rt?.flushTimer) clearTimeout(rt.flushTimer);
   live.runtimes.delete(shareId);
@@ -110,6 +134,7 @@ export function startLive(): void {
   if (live.started) return;
   live.started = true;
   addTap(onMessage);
+  addTap((sessionId, m) => onDriveMessage(sessionId, m, fx));
   for (const row of activeLiveShares()) attach(row);
   setInterval(sweep, SWEEP_MS).unref();
 }
@@ -141,6 +166,8 @@ export async function createLive(
 ): Promise<LiveView> {
   startLive();
   const session = getSession(sessionId);
+  if (level === "drive" && driveRefusal(session))
+    throw new ShareError(`Drive: ${driveRefusal(session)}.`, 400);
   if (activeLiveShareFor(sessionId))
     throw new ShareError("This session already has a live link.", 409);
   const ctx = shareContext();
@@ -171,16 +198,46 @@ export async function createLive(
 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);
+  const option = levelOptions(sessionOrNull(rt.share.session_id)).find(
+    (o) => o.value === level
+  );
+  if (!option?.enabled)
+    throw new ShareError(
+      `${LEVELS[level].label} isn't available${option?.reason ? `: ${option.reason}` : ""}.`,
+      400
+    );
   if (rt.share.level === level) return;
-  // Synchronous and first: from here the machine treats the share as `level`.
+  // Synchronous and first: from here the machine treats the share as
+  // `level`, so a racing Drive prompt is refused. Then what Drive left goes.
   rt.share = { ...rt.share, level };
   setLevel(id, level);
+  if (level !== "drive") setWheel(rt, null, "downgraded", fx);
   rt.notice = null;
   live.socket?.send(id, "access", { level });
 }
 
+/** Gives the wheel to an admitted guest of a Drive share, or takes it back (null). */
+export function giveWheel(id: string, guestId: string | null): void {
+  const rt = runtimeFor(id);
+  if (rt.share.level !== "drive")
+    throw new ShareError("Drive is off for this share.", 409);
+  if (guestId) {
+    const g = rt.guests.get(guestId);
+    if (g?.status !== "admitted" || !admittedGuestIds(id).has(guestId))
+      throw new ShareError("That guest isn't in the session.", 404);
+    const s = sessionOrNull(rt.share.session_id);
+    const why = s ? driveRefusal(s) : "This session is gone";
+    if (why) throw new ShareError(`Drive: ${why}.`, 409);
+  }
+  if ((rt.drive.wheel?.guestId ?? null) === guestId) return;
+  setWheel(rt, guestId, "taken_back", fx);
+  rt.notice = null;
+  live.socket?.send(id, "access", {
+    level: "drive",
+    driver_guest_id: guestId,
+  });
+}
+
 /** What the invite dialog offers for a session. */
 export function inviteFor(sessionId: string): LiveInvite {
   const count = Math.min(
@@ -190,7 +247,7 @@ export function inviteFor(sessionId: string): LiveInvite {
     RING_ITEMS
   );
   return {
-    levels: levelOptions(),
+    levels: levelOptions(sessionOrNull(sessionId)),
     history: {
       label: `Include the ${count} earlier message${count === 1 ? "" : "s"}`,
       default: true,
@@ -201,7 +258,8 @@ export function inviteFor(sessionId: string): LiveInvite {
 
 /** Ends access: Connect disconnects every guest, then this machine lets go. */
 export async function endLive(id: string): Promise<void> {
-  runtimeFor(id);
+  // Before anything awaits: no Drive prompt is taken in from here.
+  releaseDrive(runtimeFor(id), "ended", fx);
   await revokeRemote(id);
   markLiveEnded(id);
   stop(id);
@@ -225,14 +283,23 @@ function logGuest(rt: Runtime, kind: "admit" | "deny" | "kick", g: Guest) {
   });
 }
 
-export function admit(id: string, guestId: string): void {
+export function admit(
+  id: string,
+  guestId: string,
+  opts: { drive?: boolean } = {}
+): void {
   const rt = runtimeFor(id);
   const g = guestOf(rt, guestId);
   if (g.status !== "pending") throw new ShareError("Already let in.", 409);
+  if (opts.drive && rt.share.level !== "drive")
+    throw new ShareError("Drive is off for this share.", 409);
+  if (opts.drive && rt.drive.wheel)
+    throw new ShareError("Someone else is driving.", 409);
   logGuest(rt, "admit", g);
   g.status = "admitted";
   rt.notice = null;
   live.socket?.send(id, "admit", { guest_id: g.id });
+  if (opts.drive) giveWheel(id, g.id);
 }
 
 export function deny(id: string, guestId: string): void {
@@ -247,6 +314,7 @@ export function deny(id: string, guestId: string): void {
 export function kick(id: string, guestId: string): void {
   const rt = runtimeFor(id);
   const g = guestOf(rt, guestId);
+  if (rt.drive.wheel?.guestId === g.id) setWheel(rt, null, "kicked", fx);
   logGuest(rt, "kick", g);
   rt.guests.delete(g.id);
   live.socket?.send(id, "kick", { guest_id: g.id });
@@ -266,8 +334,10 @@ export async function sendSuggestion(
   const rt = runtimeFor(id);
   const card = openSuggestions(id).find((s) => s.id === suggestionId);
   if (!card) throw new ShareError("That suggestion is gone.", 404);
-  const text = cleanBody(edited ?? card.text);
-  if (!text) throw new ShareError("The message is empty.", 400);
+  const body = cleanBody(edited ?? card.text);
+  if (!body) throw new ShareError("The message is empty.", 400);
+  // It started as a guest's text, edited or not.
+  const text = noMentions(body);
   const key = `${id}:${suggestionId}`;
   if (sending.has(key)) throw new ShareError("Already sending.", 409);
   sending.add(key);
@@ -275,6 +345,7 @@ export async function sendSuggestion(
     await sendChatConfirmed(rt.share.session_id, {
       text,
       origin: { kind: "guest", label: card.guestName },
+      host: true,
     });
     logLive({
       share_id: id,
@@ -327,6 +398,9 @@ export function viewOf(id: string, now = Date.now()): LiveView | null {
     names.set(k, (names.get(k) ?? 0) + 1);
   }
   const admitted = admittedGuestIds(id);
+  const session = sessionOrNull(rt.share.session_id);
+  const levels = levelOptions(session);
+  const canDrive = !!levels.find((l) => l.value === "drive")?.enabled;
   return {
     id,
     sessionId: rt.share.session_id,
@@ -338,8 +412,9 @@ export function viewOf(id: string, now = Date.now()): LiveView | null {
     connected: live.socket?.connected ?? false,
     notice: rt.notice,
     level: rt.share.level,
-    levels: levelOptions(),
+    levels,
     history: rt.share.history === 1,
+    ...driveView(rt),
     guests: shown
       .filter((g) => g.status === "pending" || admitted.has(g.id))
       .map((g) => ({
@@ -349,7 +424,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),
+        actions: guestActions(rt, g, canDrive),
       })),
     suggestions: openSuggestions(id),
   };

package/lib/live/store.ts

@@ -24,7 +24,13 @@ export type LogKind =
   | "suggestion"
   | "sent"
   | "dismissed"
-  | "level";
+  | "level"
+  // Drive: who holds the wheel (guest_id, ref = the wheel's own id; both
+  // null when taken back), a prompt they sent (ref = its id), and why a
+  // Drive's turn or queue was stopped (ref = the reason).
+  | "wheel"
+  | "drive_prompt"
+  | "drive_stopped";
 
 export interface LogRow {
   id: number;
@@ -148,6 +154,33 @@ export function admittedGuestIds(shareId: string): Set<string> {
   return out;
 }
 
+/** Who holds the wheel, from the log: a kick or a level other than Drive drops it. */
+export function wheelOf(
+  shareId: string
+): { guestId: string; wheel: string } | null {
+  let w: { guestId: string; wheel: string } | null = null;
+  for (const l of listLog(shareId)) {
+    if (l.kind === "wheel")
+      w = l.guest_id && l.ref ? { guestId: l.guest_id, wheel: l.ref } : null;
+    else if (l.kind === "level" && l.ref !== "drive") w = null;
+    else if (
+      (l.kind === "kick" || l.kind === "deny") &&
+      l.guest_id === w?.guestId
+    )
+      w = null;
+  }
+  return w;
+}
+
+/** Whether a Drive prompt with this id was ever logged for the share. */
+export function hasDrivePrompt(shareId: string, ref: string): boolean {
+  return !!db
+    .prepare(
+      `SELECT 1 FROM live_share_log WHERE share_id = ? AND kind = 'drive_prompt' AND ref = ? LIMIT 1`
+    )
+    .get(shareId, ref);
+}
+
 /** Whether a suggestion with this id was ever logged for the share. */
 export function hasSuggestion(shareId: string, ref: string): boolean {
   return !!db

package/lib/live/testing.ts

@@ -0,0 +1,281 @@
+/**
+ * For tests: a fake Connect (its control API and its cable) and a Drive-ready
+ * task session, so a test can mint a live share, play Connect's side of the
+ * socket and watch what goes up. Import it before ./service.
+ */
+
+import crypto from "crypto";
+import fs from "fs";
+import http from "http";
+import path from "path";
+import { randomUUID } from "crypto";
+import type { AddressInfo } from "net";
+import { tempDir } from "@/lib/test-temp";
+import type { WorkerCommand } from "@/lib/chat/worker/protocol";
+
+export const SHARE = "live00000001";
+
+export async function liveHarness() {
+  const dir = tempDir("agentos-live-");
+  const keys = crypto.generateKeyPairSync("ed25519");
+  const seen: { method: string; url: string; body: string }[] = [];
+  const server = http.createServer((req, res) => {
+    let body = "";
+    req.on("data", (c) => (body += c));
+    req.on("end", () => {
+      seen.push({ method: req.method!, url: req.url!, body });
+      const mint = req.method === "POST" && req.url!.endsWith("/live-shares");
+      res.writeHead(mint ? 201 : 200, { "Content-Type": "application/json" });
+      res.end(
+        JSON.stringify(
+          mint
+            ? {
+                id: SHARE,
+                url: "https://runagentos.com/s/tok",
+                status: "active",
+                expires_at: new Date(Date.now() + 3600_000).toISOString(),
+                ends_with_session: false,
+                max_guests: 5,
+              }
+            : { id: SHARE, status: "revoked" }
+        )
+      );
+    });
+  });
+  await new Promise<void>((r) => server.listen(0, "127.0.0.1", r));
+  process.env.AGENTOS_CONNECT_DIR = dir;
+  fs.writeFileSync(
+    path.join(dir, "connect.json"),
+    JSON.stringify({
+      machineId: "abcd1234",
+      hostname: "m-0123456789abcdef.runagentos.com",
+      apiUrl: `http://127.0.0.1:${(server.address() as AddressInfo).port}`,
+      enabled: true,
+    }),
+    { mode: 0o600 }
+  );
+  fs.writeFileSync(
+    path.join(dir, "machine.key"),
+    keys.privateKey.export({ type: "pkcs8", format: "pem" }).toString(),
+    { mode: 0o600 }
+  );
+
+  const { live } = await import("./runtime");
+  const svc = await import("./service");
+  const { getDb } = await import("@/lib/db");
+  const { createProject } = await import("@/lib/projects");
+  const { seedSession } = await import("@/lib/orchestrator/testing");
+  const { writePart } = await import("@/lib/db/session-parts");
+  const { partOf } = await import("@/lib/db/session-parts/columns");
+
+  /** Sets session columns, wherever each one lives. */
+  function setColumns(id: string, set: Record<string, unknown>) {
+    for (const [k, v] of Object.entries(set)) {
+      const part = partOf(k);
+      if (part) writePart(getDb(), part, id, { [k]: v } as never);
+      else
+        getDb().prepare(`UPDATE sessions SET ${k} = ? WHERE id = ?`).run(v, id);
+    }
+  }
+
+  interface Fake {
+    out: Record<string, unknown>[];
+    handlers: Record<string, (d?: unknown) => void>;
+  }
+  let fake: Fake | null = null;
+  const factory = () => {
+    const f: Fake = { out: [], handlers: {} };
+    fake = f;
+    return {
+      readyState: 1,
+      send: (d: string) => f.out.push(JSON.parse(d)),
+      close: () => {},
+      terminate: () => {},
+      on: (e: string, fn: (d?: unknown) => void) => {
+        f.handlers[e] = fn;
+      },
+    };
+  };
+  const ident = JSON.stringify({ channel: "LiveHostChannel", share_id: SHARE });
+
+  /** A frame from Connect, as it arrives on the cable. */
+  const down = (frame: Record<string, unknown>) =>
+    fake!.handlers.message(
+      JSON.stringify({
+        identifier: ident,
+        message: { share_id: SHARE, ...frame },
+      })
+    );
+
+  /** What this machine sent up, by action. */
+  const up = (action?: string) =>
+    fake!.out
+      .filter((m) => m.command === "message")
+      .map((m) => JSON.parse(m.data as string) as Record<string, unknown>)
+      .filter((m) => !action || m.action === action);
+
+  /** A Claude task chat in its own worktree: what Drive needs. */
+  function taskChat(
+    cwd = tempDir("agentos-wt-"),
+    change: Record<string, unknown> = {}
+  ): string {
+    const project = createProject({
+      name: `p-${randomUUID().slice(0, 6)}`,
+      workingDirectory: tempDir("agentos-main-"),
+    });
+    const id = seedSession({
+      projectId: project.id,
+      name: "Pairing",
+      view: "chat",
+      task: true,
+    });
+    setColumns(id, {
+      agent_type: "claude",
+      task_prompt: "build the thing",
+      worktree_path: cwd,
+      working_directory: cwd,
+      ...change,
+    });
+    return id;
+  }
+
+  async function open(
+    sessionId: string,
+    level: "watch" | "suggest" | "drive" = "drive"
+  ) {
+    const view = await svc.createLive(sessionId, "1h", level, true);
+    fake!.handlers.message(JSON.stringify({ type: "welcome" }));
+    fake!.handlers.message(
+      JSON.stringify({ type: "confirm_subscription", identifier: ident })
+    );
+    return view;
+  }
+
+  function admit(gid = "g00000000001", name = "Ahmed", drive = false) {
+    down({ type: "join_request", guest: { id: gid, name } });
+    svc.admit(SHARE, gid, { drive });
+    down({ type: "presence", guest: { id: gid, name }, online: true });
+  }
+
+  const { gatedHost, tick } = await import("@/lib/chat/worker/gate-testing");
+  const { registry, getSession } = await import("@/lib/chat/registry");
+  const { listQueue } = await import("@/lib/chat/queued");
+  const { onDriveMessage } = await import("./drive");
+  const publisher = await import("./publisher");
+  const fx = {
+    send: (id: string, action: string, data?: Record<string, unknown>) =>
+      live.socket?.send(id, action, data),
+  };
+  const settle = async () => {
+    for (let i = 0; i < 6; i++) await tick();
+  };
+
+  /**
+   * A task chat with its live share at `level`, a guest admitted (at the
+   * wheel unless suggest), and a real chat worker over a stub agent
+   * registered as its live one. The test file mocks the drivers with
+   * gate-testing's. `publish` also sends its items up, as the publisher
+   * would (paced, so statuses can arrive late).
+   */
+  async function driving(
+    opts: {
+      level?: "suggest" | "drive";
+      guestId?: string;
+      publish?: boolean;
+    } = {}
+  ) {
+    const guestId = opts.guestId ?? "g00000000001";
+    const sessionId = taskChat();
+    const session = getSession(sessionId);
+    const commands: WorkerCommand[] = [];
+    const w = await gatedHost(session, session.worktree_path!, (e) => {
+      const entry = registry.live.get(sessionId);
+      if (e.type === "state" && entry) entry.state = e.state;
+      if (e.type === "item" || e.type === "state") {
+        onDriveMessage(sessionId, e, fx);
+        if (opts.publish) publisher.onMessage(sessionId, e);
+      }
+      if (e.type === "queue")
+        onDriveMessage(
+          sessionId,
+          { type: "queue", queue: listQueue(sessionId) },
+          fx
+        );
+    });
+    registry.live.set(sessionId, {
+      worker: {
+        command: (c: WorkerCommand) => {
+          commands.push(c);
+          void w.host.handle(c);
+        },
+      },
+      state: "idle",
+      streaming: new Map(),
+      activity: null,
+      canGuestGate: true,
+    } as never);
+    await open(sessionId, opts.level ?? "drive");
+    admit(guestId, "Ahmed", opts.level !== "suggest");
+    const prompt = async (
+      id: string,
+      text = "add a test for the parser",
+      gid = guestId
+    ) => {
+      down({
+        type: "drive_prompt",
+        id,
+        guest: { id: gid, name: "Ahmed" },
+        text,
+      });
+      await settle();
+    };
+    const statuses = (id?: string) =>
+      up("drive_status").filter((s) => !id || s.id === id);
+    const sends = () => commands.filter((c) => c.type === "send");
+    const done = () => {
+      w.host.close();
+      registry.live.delete(sessionId);
+    };
+    return {
+      sessionId,
+      w,
+      commands,
+      sends,
+      prompt,
+      statuses,
+      done,
+      rt: () => live.runtimes.get(SHARE)!,
+    };
+  }
+
+  function reset() {
+    for (const id of [...live.runtimes.keys()]) live.runtimes.delete(id);
+    live.socket?.close();
+    live.socket = svc.makeSocket(factory as never);
+    fake = null;
+    seen.length = 0;
+    getDb().prepare(`DELETE FROM live_shares`).run();
+    getDb().prepare(`DELETE FROM live_share_log`).run();
+  }
+
+  function close() {
+    live.socket?.close();
+    server.close();
+  }
+
+  return {
+    live,
+    svc,
+    seen,
+    down,
+    up,
+    taskChat,
+    setColumns,
+    open,
+    driving,
+    settle,
+    admit,
+    reset,
+    close,
+  };
+}

package/lib/live/types.ts

@@ -25,10 +25,12 @@ export interface LevelOption {
 }
 
 export interface GuestAction {
-  kind: "kick" | "admit" | "deny";
+  kind: "kick" | "admit" | "admit_drive" | "deny" | "give_wheel" | "take_back";
   label: string;
 }
 
+export type DriverState = "idle" | "queued" | "working" | "waiting_on_host";
+
 // What the host's screens show of a live share (served by /api/live-shares).
 export interface LiveView {
   id: string;
@@ -44,6 +46,13 @@ export interface LiveView {
   levels: LevelOption[];
   /** Whether the guests got the chat from before the link was made. */
   history: boolean;
+  /** The guest holding the wheel on a Drive share. */
+  driver: { guestId: string; name: string; state: DriverState } | null;
+  /** Shown above the composer while a guest drives. */
+  banner: {
+    text: string;
+    action?: { kind: "take_back"; label: string };
+  } | null;
   guests: {
     id: string;
     name: string;

package/package.json

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