@saadnvd1/agent-os 0.3.779 → 0.3.781

package/lib/live/inbox.ts

@@ -1,7 +1,10 @@
 /**
  * What Connect sends down. Only the types below are accepted, and only for a
  * share this machine minted and still holds. Everything else is dropped and
- * counted: nothing downward is executed, interpreted or sent on to an agent.
+ * counted: nothing downward is executed or interpreted, and only a Drive
+ * prompt from the guest this machine gave the wheel reaches an agent
+ * (./drive decides). No type answers an approval, sets the level or moves
+ * the wheel: those come only from the host's own API.
  */
 
 import { z } from "zod";
@@ -14,8 +17,10 @@ import {
   logLive,
   markLiveEnded,
   openSuggestions,
+  setLevel,
 } from "./store";
 import { MAX_LOBBY, MAX_PENDING_CARDS, live, type Runtime } from "./runtime";
+import { acceptPrompt, setWheel, stopPrompt } from "./drive";
 
 export const DOWNWARD = [
   "roster",
@@ -28,6 +33,9 @@ export const DOWNWARD = [
   "invalid",
   "admit_failed",
   "access_failed",
+  "drive_prompt",
+  "drive_stop",
+  "code_locked",
 ] as const;
 
 const id = z.string().min(1).max(64);
@@ -46,6 +54,9 @@ const SCHEMAS = {
   invalid: z.object({}),
   admit_failed: z.object({ guest_id: id.optional(), reason: z.string() }),
   access_failed: z.object({ reason: z.string().max(200).optional() }),
+  drive_prompt: z.object({ id, guest, text: z.string().max(16000) }),
+  drive_stop: z.object({ id, guest }),
+  code_locked: z.object({ until: z.string().max(40) }),
 } satisfies Record<(typeof DOWNWARD)[number], z.ZodType>;
 
 export interface InboxEffects {
@@ -139,6 +150,7 @@ export function handleFrame(
       const g = (parsed.data as z.infer<typeof SCHEMAS.guest_left>).guest;
       const known = rt.guests.get(g.id);
       if (!known) return true;
+      if (rt.drive.wheel?.guestId === g.id) setWheel(rt, null, "left", fx);
       if (known.status === "pending") rt.guests.delete(g.id);
       else known.online = false;
       return true;
@@ -201,9 +213,44 @@ export function handleFrame(
       rt.notice = "Your plan's guest limit is reached.";
       return true;
     }
-    case "access_failed":
-      rt.notice = "Connect refused that access level.";
+    case "access_failed": {
+      const why = (parsed.data as z.infer<typeof SCHEMAS.access_failed>).reason;
+      rt.notice = why
+        ? why.replace(/\s+/g, " ").trim().slice(0, 160)
+        : "Connect refused that access level.";
+      // Connect didn't take it: this machine goes back to the safer side.
+      if (rt.drive.wheel) setWheel(rt, null, "taken_back", fx);
+      if (rt.share.level === "drive") {
+        rt.share = { ...rt.share, level: "suggest" };
+        setLevel(shareId, "suggest");
+        fx.send(shareId, "access", { level: "suggest" });
+      }
+      return true;
+    }
+    case "code_locked": {
+      const until = Date.parse(
+        (parsed.data as z.infer<typeof SCHEMAS.code_locked>).until
+      );
+      rt.codeLockedUntil = Number.isFinite(until) ? until : null;
       return true;
+    }
+    case "drive_prompt":
+      return acceptPrompt(
+        rt,
+        parsed.data as z.infer<typeof SCHEMAS.drive_prompt>,
+        fx,
+        now
+      )
+        ? true
+        : (drop("duplicate drive prompt"), false);
+    case "drive_stop":
+      return stopPrompt(
+        rt,
+        parsed.data as z.infer<typeof SCHEMAS.drive_stop>,
+        fx
+      )
+        ? true
+        : (drop("stop from a guest not driving"), false);
     case "invalid":
       rt.drops++;
       return true;

package/lib/live/levels.ts

@@ -1,29 +1,74 @@
+import type { Session } from "../db";
 import {
   LEVELS,
+  type DriverState,
   type GuestAction,
   type LevelOption,
   type LiveLevel,
+  type LiveView,
 } from "./types";
+import { driveRefusal, driverState } from "./drive";
 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[] {
+export function levelOptions(session: Session | null): LevelOption[] {
+  const why = session ? driveRefusal(session) : "Task sessions only";
   return ORDER.map((value) => ({
     value,
     ...LEVELS[value],
-    ...(value === "drive"
-      ? { enabled: false, reason: "Coming soon" }
+    ...(value === "drive" && why
+      ? { enabled: false, reason: why }
       : { 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" }];
+export function guestActions(
+  rt: Runtime,
+  g: Guest,
+  canDrive: boolean
+): GuestAction[] {
+  const drive = rt.share.level === "drive" && canDrive;
+  if (g.status === "pending")
+    return drive && !rt.drive.wheel
+      ? [
+          { kind: "admit", label: "Let in" },
+          { kind: "admit_drive", label: "Let in to drive" },
+          { kind: "deny", label: "Deny" },
+        ]
+      : [
+          { kind: "admit", label: drive ? "Let in" : "Admit" },
+          { kind: "deny", label: "Deny" },
+        ];
+  const kick: GuestAction = { kind: "kick", label: "Kick" };
+  if (rt.share.level !== "drive") return [kick];
+  if (rt.drive.wheel?.guestId === g.id)
+    return [{ kind: "take_back", label: "Take back" }, kick];
+  return drive
+    ? [{ kind: "give_wheel", label: "Give the wheel" }, kick]
+    : [kick];
+}
+
+const DRIVING: Record<DriverState, string> = {
+  idle: "is driving",
+  queued: "is driving · prompt queued",
+  working: "is driving · working",
+  waiting_on_host: "is driving · waiting on you",
+};
+
+/** The guest holding the wheel and the banner the host sees above the composer. */
+export function driveView(rt: Runtime): Pick<LiveView, "driver" | "banner"> {
+  const w = rt.drive.wheel;
+  const g = w && rt.guests.get(w.guestId);
+  if (rt.share.level !== "drive" || !w || !g)
+    return { driver: null, banner: null };
+  const state = driverState(rt);
+  return {
+    driver: { guestId: g.id, name: g.name, state },
+    banner: {
+      text: `${g.name} ${DRIVING[state]}`,
+      action: { kind: "take_back", label: "Take back" },
+    },
+  };
 }

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;
@@ -29,7 +48,10 @@ export interface Runtime {
   flushTimer: ReturnType<typeof setTimeout> | null;
   slowUntil: number;
   notice: string | null;
+  /** Connect locked the lobby until this time (ms) after wrong access codes. */
+  codeLockedUntil: number | 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";
@@ -9,7 +10,12 @@ import { addTap, getSession, registry } from "../chat/registry";
 import { sendChatConfirmed } from "../chat/runner";
 import { shareContext } from "../share/context";
 import { redactForShare } from "../share/redact";
-import { ShareError, createLiveRemote, revokeRemote } from "../share/connect";
+import {
+  ShareError,
+  createLiveRemote,
+  revokeRemote,
+  setAccessCodeRemote,
+} from "../share/connect";
 import type { LiveExpiry } from "../connect/control-api";
 import {
   LEVELS,
@@ -17,10 +23,21 @@ import {
   type LiveLevel,
   type LiveView,
 } from "./types";
-import { guestActions, levelOptions } from "./levels";
+import { driveView, guestActions, levelOptions } from "./levels";
+import { codeView, inviteCode } from "./code-view";
+import { codeRefusal, generateCode, normalizeCode } from "./code";
+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";
@@ -35,6 +52,7 @@ import {
   logLive,
   markLiveEnded,
   openSuggestions,
+  setAccessCode,
   setLevel,
   type LiveShareRow,
 } from "./store";
@@ -63,6 +81,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;
@@ -86,7 +116,9 @@ function attach(row: LiveShareRow): Runtime {
     flushTimer: null,
     slowUntil: 0,
     notice: null,
+    codeLockedUntil: null,
     drops: 0,
+    drive: newDrive(row.id),
   };
   live.runtimes.set(row.id, rt);
   try {
@@ -99,6 +131,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 +143,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();
 }
@@ -137,19 +171,45 @@ export async function createLive(
   sessionId: string,
   expiresIn: LiveExpiry,
   level: LiveLevel = "suggest",
-  history = true
+  history = true,
+  codeOpt?: { custom?: string } | null
 ): 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);
+  let accessCode: string | null = null;
+  if (codeOpt) {
+    if (codeOpt.custom) {
+      const why = codeRefusal(codeOpt.custom);
+      if (why) throw new ShareError(why, 400);
+    }
+    accessCode = codeOpt.custom
+      ? normalizeCode(codeOpt.custom)
+      : generateCode();
+  }
   const ctx = shareContext();
   const title =
     redactForShare(session.name, ctx)
       .text.replace(/\s+/g, " ")
       .trim()
       .slice(0, 120) || "Chat";
-  const made = await createLiveRemote({ title, expiresIn, access: level });
+  const made = await createLiveRemote({
+    title,
+    expiresIn,
+    access: level,
+    ...(accessCode ? { accessCode } : {}),
+  });
+  // An old Connect ignores the code and would let anyone reach the lobby.
+  if (accessCode && !made.access_code) {
+    await revokeRemote(made.id).catch(() => {});
+    throw new ShareError(
+      "Connect doesn't support access codes yet. Try again without one.",
+      502
+    );
+  }
   const row: LiveShareRow = {
     id: made.id,
     session_id: sessionId,
@@ -162,6 +222,7 @@ export async function createLive(
     ended_at: null,
     level,
     history: history ? 1 : 0,
+    access_code: accessCode,
   };
   insertLiveShare(row);
   attach(row);
@@ -171,16 +232,70 @@ 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 });
 }
 
+/**
+ * Turns the access code on (generate, or the host's own), changes it, or turns
+ * it off (null). Connect first: if it doesn't confirm, nothing changes here.
+ * Guests already in or waiting keep their seat; only new joins need the code.
+ */
+export async function changeCode(
+  id: string,
+  next: { generate: true } | { code: string } | null
+): Promise<void> {
+  const rt = runtimeFor(id);
+  let code: string | null = null;
+  if (next && "code" in next) {
+    const why = codeRefusal(next.code);
+    if (why) throw new ShareError(why, 400);
+    code = normalizeCode(next.code);
+  } else if (next) code = generateCode();
+  await setAccessCodeRemote(id, code);
+  const now = live.runtimes.get(id);
+  if (!now || now.share.ended_at) return;
+  now.share = { ...now.share, access_code: code };
+  setAccessCode(id, code);
+  now.codeLockedUntil = null;
+}
+
+/** 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,18 +305,20 @@ 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,
       count,
     },
+    code: inviteCode(),
   };
 }
 
 /** 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 +342,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 +373,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 +393,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 +404,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 +457,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 +471,10 @@ 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,
+    code: codeView(rt, now),
     history: rt.share.history === 1,
+    ...driveView(rt),
     guests: shown
       .filter((g) => g.status === "pending" || admitted.has(g.id))
       .map((g) => ({
@@ -349,7 +484,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

@@ -14,6 +14,8 @@ export interface LiveShareRow {
   level: LiveLevel;
   /** 1: guests get the chat from before the link was made. */
   history: number;
+  /** The access code in plain text, or null when off. Never logged. */
+  access_code: string | null;
 }
 
 export type LogKind =
@@ -24,7 +26,15 @@ export type LogKind =
   | "suggestion"
   | "sent"
   | "dismissed"
-  | "level";
+  | "level"
+  // The code was turned on, off or changed; the log never holds the code.
+  | "code_changed"
+  // 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;
@@ -41,8 +51,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, level, history)
-     VALUES (@id, @session_id, @title, @url, @ends_with_session, @max_guests, @created_at, @expires_at, @ended_at, @level, @history)`
+       (id, session_id, title, url, ends_with_session, max_guests, created_at, expires_at, ended_at, level, history, access_code)
+     VALUES (@id, @session_id, @title, @url, @ends_with_session, @max_guests, @created_at, @expires_at, @ended_at, @level, @history, @access_code)`
   ).run(row);
 }
 
@@ -88,6 +98,22 @@ export function setLevel(id: string, level: LiveLevel): void {
   });
 }
 
+export function setAccessCode(id: string, code: string | null): void {
+  db.prepare(`UPDATE live_shares SET access_code = ? WHERE id = ?`).run(
+    code,
+    id
+  );
+  logLive({
+    share_id: id,
+    kind: "code_changed",
+    guest_id: null,
+    guest_name: null,
+    ref: code ? "on" : "off",
+    text: null,
+    sent_text: null,
+  });
+}
+
 export function logLive(
   row: Omit<LogRow, "id" | "at"> & { at?: number }
 ): void {
@@ -148,6 +174,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