@saadnvd1/agent-os 0.3.775 → 0.3.778

package/lib/live/frames.ts

@@ -0,0 +1,132 @@
+/**
+ * What goes up to Connect for one chat item, or nothing. Which items a
+ * guest may see is decided by the shared snapshot rules (toRaw); this only
+ * shapes them into frames. Text is redacted whole, never as a delta.
+ */
+
+import type { ChatItem, ChatState } from "../chat/events";
+import { isSecretPath } from "../secret-paths";
+import { toRaw, strings } from "../share/snapshot";
+import { redactForShare, type ShareContext } from "./../share/redact";
+
+export type ItemFrame =
+  | {
+      id: string;
+      kind: "user" | "assistant" | "note";
+      text: string;
+      from?: string;
+      at: number;
+    }
+  | {
+      id: string;
+      kind: "tool";
+      name: string;
+      summary: string;
+      status: "running" | "done" | "error";
+      at: number;
+    };
+
+export type LiveState = "working" | "idle" | "waiting_on_host";
+
+export const MAX_TEXT_BYTES = 24 * 1024;
+export const MAX_SUMMARY_BYTES = 200;
+const MAX_NAME_BYTES = 64;
+const MAX_ID = 64;
+
+/** The longest prefix of `s` that fits in `max` bytes, cut on a character. */
+export function clipBytes(s: string, max: number): string {
+  if (Buffer.byteLength(s) <= max) return s;
+  let out = "";
+  let size = 0;
+  for (const ch of s) {
+    const n = Buffer.byteLength(ch);
+    if (size + n > max) break;
+    out += ch;
+    size += n;
+  }
+  return out;
+}
+
+const oneLine = (s: string) => s.replace(/\s+/g, " ").trim();
+
+export function stateOf(state: ChatState): LiveState {
+  if (state === "running") return "working";
+  if (state === "waiting") return "waiting_on_host";
+  return "idle";
+}
+
+// Messages that were not typed by the reader (the agent bus, schedules,
+// AgentOS itself) stay on this machine; a sent suggestion is the reader's.
+function userFrom(item: Extract<ChatItem, { kind: "user" }>): string | null {
+  const o = item.origin;
+  if (!o) return item.peer || item.from ? null : "host";
+  if (o.kind === "guest") return `guest:${o.label}`;
+  if (o.kind === "decision") return "host";
+  return null;
+}
+
+export interface ItemMapper {
+  /** `text` replaces the item's own text (an assistant turn still streaming). */
+  (item: ChatItem, text?: string): ItemFrame | null;
+}
+
+export function itemMapper(ctx: ShareContext): ItemMapper {
+  const take = (s: string) => redactForShare(s, ctx).text;
+  return (item, text) => {
+    const at = item.createdAt ?? Date.now();
+    const id = item.id.slice(0, MAX_ID);
+    if (item.kind === "tool") {
+      const secret = strings(item.input).some(isSecretPath);
+      const label = secret ? item.name : item.title || item.name;
+      const status =
+        item.status === "running"
+          ? "running"
+          : item.status === "done"
+            ? "done"
+            : "error";
+      return {
+        id,
+        kind: "tool",
+        name: clipBytes(oneLine(take(item.name)), MAX_NAME_BYTES),
+        summary: clipBytes(oneLine(take(label)), MAX_SUMMARY_BYTES),
+        status,
+        at,
+      };
+    }
+    if (item.kind === "todos") {
+      const done = item.todos.filter((t) => t.status === "completed").length;
+      return {
+        id,
+        kind: "note",
+        text: `To do: ${done} of ${item.todos.length} done`,
+        at,
+      };
+    }
+    let from: string | undefined;
+    if (item.kind === "user") {
+      const f = userFrom(item);
+      if (!f) return null;
+      from = f;
+    }
+    const raw = toRaw(item);
+    if (!raw || raw.tools || raw.type === "artifact") return null;
+    const body = clipBytes(take(text ?? raw.text), MAX_TEXT_BYTES);
+    if (item.kind === "user")
+      return {
+        id,
+        kind: "user",
+        text: body,
+        from,
+        at,
+      };
+    if (item.kind === "assistant")
+      return body.trim() ? { id, kind: "assistant", text: body, at } : null;
+    // Plans, errors and the compaction divider are one-line notes.
+    return {
+      id,
+      kind: "note",
+      text: clipBytes(oneLine(body), 400) || "…",
+      at,
+    };
+  };
+}

package/lib/live/inbox.ts

@@ -0,0 +1,225 @@
+/**
+ * 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.
+ */
+
+import { z } from "zod";
+import { cleanBody, cleanName } from "./clean";
+import { chunk } from "./ring";
+import {
+  admittedGuestIds,
+  hasJoinRequest,
+  hasSuggestion,
+  logLive,
+  markLiveEnded,
+  openSuggestions,
+} from "./store";
+import { MAX_LOBBY, MAX_PENDING_CARDS, live, type Runtime } from "./runtime";
+
+export const DOWNWARD = [
+  "roster",
+  "join_request",
+  "presence",
+  "suggestion",
+  "guest_left",
+  "ended",
+  "slow_down",
+  "invalid",
+  "admit_failed",
+] as const;
+
+const id = z.string().min(1).max(64);
+const guest = z.object({ id, name: z.string().max(400) });
+
+const SCHEMAS = {
+  roster: z.object({
+    guests: z.array(guest.extend({ status: z.string().max(32) })).max(100),
+  }),
+  join_request: z.object({ guest }),
+  presence: z.object({ guest, online: z.boolean() }),
+  suggestion: z.object({ id, guest, text: z.string().max(8000) }),
+  guest_left: z.object({ guest }),
+  ended: z.object({}),
+  slow_down: z.object({}),
+  invalid: z.object({}),
+  admit_failed: z.object({ guest_id: id.optional(), reason: z.string() }),
+} satisfies Record<(typeof DOWNWARD)[number], z.ZodType>;
+
+export interface InboxEffects {
+  send: (
+    shareId: string,
+    action: string,
+    data?: Record<string, unknown>
+  ) => void;
+  /** The share is over: stop publishing and drop the subscription. */
+  ended: (shareId: string) => void;
+}
+
+const dropped = { count: 0 };
+export const droppedCount = () => dropped.count;
+
+function drop(why: string) {
+  dropped.count++;
+  console.warn(`live: dropped a frame from Connect (${why})`);
+}
+
+/** Handles one frame for the share it arrived on. Returns whether it was used. */
+export function handleFrame(
+  shareId: string,
+  frame: Record<string, unknown>,
+  fx: InboxEffects,
+  now = Date.now()
+): boolean {
+  const rt = live.runtimes.get(shareId);
+  if (!rt || rt.share.ended_at) return (drop("unknown share"), false);
+  const type = frame.type;
+  if (
+    typeof type !== "string" ||
+    !(DOWNWARD as readonly string[]).includes(type)
+  )
+    return (drop("type not allowed"), false);
+  if (frame.share_id !== undefined && frame.share_id !== shareId)
+    return (drop("another share"), false);
+  const parsed = SCHEMAS[type as keyof typeof SCHEMAS].safeParse(frame);
+  if (!parsed.success) return (drop(`bad ${type}`), false);
+
+  switch (type) {
+    case "roster": {
+      const admitted = admittedGuestIds(shareId);
+      for (const g of (parsed.data as z.infer<typeof SCHEMAS.roster>).guests) {
+        const name = cleanName(g.name);
+        if (!name) continue;
+        if (admitted.has(g.id)) setGuest(rt, g.id, name, "admitted", now);
+        else if (g.status === "pending") {
+          if (!rt.guests.has(g.id) && pendingCount(rt) >= MAX_LOBBY) continue;
+          setGuest(rt, g.id, name, "pending", now);
+        }
+      }
+      return true;
+    }
+    case "join_request": {
+      const g = (parsed.data as z.infer<typeof SCHEMAS.join_request>).guest;
+      const name = cleanName(g.name);
+      if (!name) return (drop("bad name"), false);
+      if (rt.guests.has(g.id)) return true;
+      if (pendingCount(rt) >= MAX_LOBBY) {
+        fx.send(shareId, "deny", { guest_id: g.id });
+        return true;
+      }
+      setGuest(rt, g.id, name, "pending", now);
+      if (!hasJoinRequest(shareId, g.id))
+        logLive({
+          share_id: shareId,
+          kind: "join_request",
+          guest_id: g.id,
+          guest_name: name,
+          ref: null,
+          text: null,
+          sent_text: null,
+        });
+      return true;
+    }
+    case "presence": {
+      const p = parsed.data as z.infer<typeof SCHEMAS.presence>;
+      const known = rt.guests.get(p.guest.id);
+      if (!known || known.status !== "admitted") return true;
+      known.online = p.online;
+      if (p.online) {
+        const frames = chunk(rt.ring.list());
+        for (const items of frames)
+          fx.send(shareId, "catchup", { guest_id: known.id, items });
+        if (!frames.length) return true;
+      }
+      return true;
+    }
+    case "guest_left": {
+      const g = (parsed.data as z.infer<typeof SCHEMAS.guest_left>).guest;
+      const known = rt.guests.get(g.id);
+      if (!known) return true;
+      if (known.status === "pending") rt.guests.delete(g.id);
+      else known.online = false;
+      return true;
+    }
+    case "suggestion": {
+      const s = parsed.data as z.infer<typeof SCHEMAS.suggestion>;
+      const known = rt.guests.get(s.guest.id);
+      // Only a guest this machine let in can leave a card.
+      if (!known || known.status !== "admitted")
+        return (drop("suggestion from a guest not admitted here"), false);
+      const text = cleanBody(s.text);
+      if (!text) return (drop("empty suggestion"), false);
+      if (hasSuggestion(shareId, s.id))
+        return (drop("duplicate suggestion"), false);
+      if (openSuggestions(shareId).length >= MAX_PENDING_CARDS) {
+        fx.send(shareId, "suggestion_status", {
+          guest_id: known.id,
+          id: s.id,
+          status: "dismissed",
+        });
+        return true;
+      }
+      logLive({
+        share_id: shareId,
+        kind: "suggestion",
+        guest_id: known.id,
+        guest_name: known.name,
+        ref: s.id,
+        text,
+        sent_text: null,
+      });
+      return true;
+    }
+    case "ended":
+      markLiveEnded(shareId);
+      fx.ended(shareId);
+      return true;
+    case "slow_down":
+      rt.slowUntil = now + 5000;
+      return true;
+    case "admit_failed": {
+      const gid = (parsed.data as z.infer<typeof SCHEMAS.admit_failed>)
+        .guest_id;
+      const g = gid ? rt.guests.get(gid) : undefined;
+      if (g) g.status = "pending";
+      // The admit line must not outlive a refused admit.
+      if (gid && admittedGuestIds(shareId).has(gid))
+        logLive({
+          share_id: shareId,
+          kind: "deny",
+          guest_id: gid,
+          guest_name: g?.name ?? null,
+          ref: null,
+          text: null,
+          sent_text: null,
+        });
+      rt.notice = "Your plan's guest limit is reached.";
+      return true;
+    }
+    case "invalid":
+      rt.drops++;
+      return true;
+  }
+  return false;
+}
+
+function pendingCount(rt: Runtime) {
+  return [...rt.guests.values()].filter((x) => x.status === "pending").length;
+}
+
+function setGuest(
+  rt: Runtime,
+  id: string,
+  name: string,
+  status: "pending" | "admitted",
+  at: number
+) {
+  const old = rt.guests.get(id);
+  rt.guests.set(id, {
+    id,
+    name,
+    status,
+    online: old?.online ?? false,
+    at: old?.at ?? at,
+  });
+}

package/lib/live/publisher.ts

@@ -0,0 +1,84 @@
+/**
+ * Chat messages of a live session, as frames for Connect. Registered as a tap
+ * beside emit() in the chat registry, only for sessions with a live share.
+ * An assistant turn is redacted whole and sent at most once a second.
+ */
+
+import type { ChatItem, ChatServerMessage } from "../chat/events";
+import { listItems } from "../chat/store";
+import { visible } from "../share/snapshot";
+import { stateOf } from "./frames";
+import { live, type Runtime } from "./runtime";
+
+const FLUSH_MS = 1000;
+const SLOW_FLUSH_MS = 4000;
+
+export function seed(rt: Runtime, sessionId: string): void {
+  for (const item of visible(listItems(sessionId))) {
+    const frame = rt.map(item);
+    if (frame) rt.ring.upsert(frame);
+  }
+}
+
+export function flush(rt: Runtime): void {
+  if (rt.flushTimer) clearTimeout(rt.flushTimer);
+  rt.flushTimer = null;
+  const batch = [...rt.dirty.values()];
+  rt.dirty.clear();
+  for (const { item, text } of batch) {
+    // A word still being typed is held back: half a key isn't recognisable.
+    const open = text !== undefined && rt.streaming.has(item.id);
+    const frame = rt.map(item, open ? text.replace(/\S+$/, "") : text);
+    if (!frame) continue;
+    rt.ring.upsert(frame);
+    live.socket?.send(rt.share.id, "item", frame);
+  }
+}
+
+function schedule(rt: Runtime, now: boolean) {
+  if (now) return flush(rt);
+  if (rt.flushTimer) return;
+  rt.flushTimer = setTimeout(
+    () => flush(rt),
+    Date.now() < rt.slowUntil ? SLOW_FLUSH_MS : FLUSH_MS
+  );
+}
+
+function mark(rt: Runtime, item: ChatItem, text?: string) {
+  rt.dirty.set(item.id, { item, text });
+}
+
+export function onMessage(sessionId: string, m: ChatServerMessage): void {
+  for (const rt of live.runtimes.values()) {
+    if (rt.share.session_id !== sessionId || rt.share.ended_at) continue;
+    if (m.type === "state") {
+      live.socket?.send(rt.share.id, "state", { state: stateOf(m.state) });
+    } else if (m.type === "item") {
+      const item = m.item;
+      if (item.kind === "turn_end") {
+        flush(rt);
+        live.socket?.send(rt.share.id, "state", { state: "idle" });
+        continue;
+      }
+      const streaming =
+        (item.kind === "assistant" || item.kind === "reasoning") &&
+        item.streaming === true;
+      if (item.kind === "assistant") {
+        if (streaming) rt.streaming.set(item.id, { item, text: item.text });
+        else rt.streaming.delete(item.id);
+      }
+      mark(
+        rt,
+        item,
+        item.kind === "assistant" && streaming ? item.text : undefined
+      );
+      schedule(rt, !streaming);
+    } else if (m.type === "delta") {
+      const cur = rt.streaming.get(m.id);
+      if (!cur) continue;
+      cur.text += m.text;
+      mark(rt, cur.item, cur.text);
+      schedule(rt, false);
+    }
+  }
+}

package/lib/live/ring.ts

@@ -0,0 +1,61 @@
+import type { ItemFrame } from "./frames";
+
+export const RING_ITEMS = 200;
+export const RING_BYTES = 512 * 1024;
+
+const sizeOf = (f: ItemFrame) => Buffer.byteLength(JSON.stringify(f));
+
+/** The last items of a share, already redacted, for guests who join late. */
+export class Ring {
+  private items = new Map<string, { frame: ItemFrame; size: number }>();
+  private bytes = 0;
+
+  upsert(frame: ItemFrame): void {
+    const old = this.items.get(frame.id);
+    if (old) this.bytes -= old.size;
+    const size = sizeOf(frame);
+    // Same slot when it already exists, so an upsert doesn't reorder the chat.
+    this.items.set(frame.id, { frame, size });
+    this.bytes += size;
+    while (this.items.size > RING_ITEMS || this.bytes > RING_BYTES) {
+      const first = this.items.keys().next().value;
+      if (first === undefined) break;
+      this.bytes -= this.items.get(first)!.size;
+      this.items.delete(first);
+    }
+  }
+
+  list(): ItemFrame[] {
+    return [...this.items.values()].map((v) => v.frame);
+  }
+
+  get size() {
+    return this.items.size;
+  }
+
+  get byteSize() {
+    return this.bytes;
+  }
+}
+
+/** Catch-up frames: at most 200 items and `maxBytes` each, in order. */
+export function chunk(
+  frames: ItemFrame[],
+  maxBytes = 48 * 1024
+): ItemFrame[][] {
+  const out: ItemFrame[][] = [];
+  let cur: ItemFrame[] = [];
+  let size = 0;
+  for (const f of frames) {
+    const n = sizeOf(f);
+    if (cur.length && (size + n > maxBytes || cur.length >= RING_ITEMS)) {
+      out.push(cur);
+      cur = [];
+      size = 0;
+    }
+    cur.push(f);
+    size += n;
+  }
+  if (cur.length) out.push(cur);
+  return out;
+}

package/lib/live/runtime.ts

@@ -0,0 +1,51 @@
+import type { ChatItem } from "../chat/events";
+import type { ShareContext } from "../share/redact";
+import type { LiveShareRow } from "./store";
+import type { ItemMapper } from "./frames";
+import { Ring } from "./ring";
+import type { LiveSocket } from "./socket";
+
+export interface Guest {
+  id: string;
+  name: string;
+  /** pending: waiting in the lobby. admitted: let in by this machine. */
+  status: "pending" | "admitted";
+  online: boolean;
+  /** When the request arrived, for the 10-minute lobby expiry. */
+  at: number;
+}
+
+/** What one live share holds in memory; everything durable is in the log. */
+export interface Runtime {
+  share: LiveShareRow;
+  guests: Map<string, Guest>;
+  ring: Ring;
+  ctx: ShareContext;
+  map: ItemMapper;
+  /** Accumulated text of assistant items still streaming, by item id. */
+  streaming: Map<string, { item: ChatItem; text: string }>;
+  /** Items waiting for the next flush, by id (latest wins). */
+  dirty: Map<string, { item: ChatItem; text?: string }>;
+  flushTimer: ReturnType<typeof setTimeout> | null;
+  slowUntil: number;
+  notice: string | null;
+  drops: number;
+}
+
+export interface LiveGlobals {
+  runtimes: Map<string, Runtime>;
+  socket: LiveSocket | null;
+  started: boolean;
+}
+
+// One per process, shared by the custom server and the route bundles.
+const g = globalThis as unknown as { __agentosLive?: LiveGlobals };
+export const live: LiveGlobals = (g.__agentosLive ??= {
+  runtimes: new Map(),
+  socket: null,
+  started: false,
+});
+
+export const LOBBY_MS = 10 * 60_000;
+export const MAX_PENDING_CARDS = 20;
+export const MAX_LOBBY = 10;