@saadnvd1/agent-os 0.3.514 → 0.3.517

package/lib/notify/copy.ts

@@ -0,0 +1,190 @@
+/**
+ * The category registry: one entry per kind of event, holding everything
+ * about it (priority, whether it's on by default, the copy, the deep link).
+ * Adding an event is one entry here. Pure, so the mobile app can sync it.
+ */
+
+import {
+  PUSH_CATEGORIES,
+  PUSH_TITLE,
+  type PushCategory,
+  type PushEnvelope,
+  type PushEnvelopeV1,
+  type PushEvent,
+  type PushLevel,
+} from "./push-types";
+import { safeId, safeKey } from "./redact";
+
+export interface CategoryDef {
+  level: PushLevel;
+  defaultOn: boolean;
+  /** Settings label. */
+  label: string;
+  /** The one word or phrase shown as the body. Fixed text, no event data. */
+  word: string;
+  /** App path for an id, or the fallback when the id is missing or unsafe. */
+  link: (id: string | null) => string;
+}
+
+/** Where a tap goes when nothing more specific is known. */
+export const FALLBACK_LINK = "/needs";
+
+export const CATEGORIES: Record<PushCategory, CategoryDef> = {
+  asks: {
+    level: "time-sensitive",
+    defaultOn: true,
+    label: "Asks",
+    word: "Needs your call",
+    link: (id) => (id ? `/orchestrator?workspaceId=${id}` : FALLBACK_LINK),
+  },
+  "needs-you": {
+    level: "active",
+    defaultOn: true,
+    label: "Waiting for you",
+    word: "Needs you",
+    link: (id) => (id ? `/session/${id}` : FALLBACK_LINK),
+  },
+  review: {
+    level: "active",
+    defaultOn: true,
+    label: "Ready for review",
+    word: "Ready for review",
+    link: (id) => (id ? `/task/${id}` : FALLBACK_LINK),
+  },
+  ci: {
+    level: "active",
+    defaultOn: true,
+    label: "CI and review problems",
+    word: "Update",
+    link: (id) => (id ? `/task/${id}` : FALLBACK_LINK),
+  },
+  merged: {
+    level: "passive",
+    defaultOn: false,
+    label: "Merged",
+    word: "Update",
+    link: (id) => (id ? `/task/${id}` : FALLBACK_LINK),
+  },
+  agents: {
+    level: "active",
+    defaultOn: true,
+    label: "Messages from agents",
+    word: "Update",
+    link: (id) => (id ? `/session/${id}` : FALLBACK_LINK),
+  },
+  digest: {
+    level: "passive",
+    defaultOn: true,
+    label: "While you're away",
+    word: "Updates",
+    link: () => FALLBACK_LINK,
+  },
+  system: {
+    level: "active",
+    defaultOn: true,
+    label: "Machine alerts",
+    word: "Update",
+    link: () => "/machines",
+  },
+};
+
+export const isPushCategory = (c: unknown): c is PushCategory =>
+  typeof c === "string" && (PUSH_CATEGORIES as readonly string[]).includes(c);
+
+export function defaultCategories(): PushCategory[] {
+  return PUSH_CATEGORIES.filter((c) => CATEGORIES[c].defaultOn);
+}
+
+/**
+ * The categories a device receives: its saved list, or the defaults when it
+ * has none. Unknown names are dropped so an old row survives a removed
+ * category.
+ */
+export function enabledCategories(
+  saved: readonly unknown[] | null | undefined
+): PushCategory[] {
+  return saved
+    ? PUSH_CATEGORIES.filter((c) => saved.includes(c))
+    : defaultCategories();
+}
+
+/**
+ * The v1 payload for an event. Built only from the registry and a vetted id
+ * and key, so it carries no event text whatever the caller passes.
+ */
+export function buildPushPayload(event: PushEvent): PushEnvelopeV1 {
+  const def = CATEGORIES[event.category];
+  const id = safeId(event.id);
+  return {
+    v: 1,
+    c: event.category,
+    t: PUSH_TITLE,
+    b: def.word,
+    l: def.link(id),
+    k: safeKey(event.key) ?? `${event.category}:${id ?? "-"}`,
+    p: def.level,
+  };
+}
+
+/**
+ * The app side: read what arrived. An unknown version or a malformed body
+ * gives the generic fallback, so a newer server never breaks an older app.
+ */
+export function parsePushEnvelope(raw: unknown): PushEnvelope {
+  const o = (raw && typeof raw === "object" ? raw : {}) as Record<
+    string,
+    unknown
+  >;
+  const category = isPushCategory(o.c) ? o.c : "system";
+  if (o.v === 1 || o.v === 2) {
+    const link =
+      typeof o.l === "string" && isAppLink(o.l)
+        ? o.l
+        : CATEGORIES[category].link(null);
+    const base = {
+      c: category,
+      t: PUSH_TITLE,
+      b: typeof o.b === "string" ? o.b.slice(0, 80) : CATEGORIES[category].word,
+      l: link,
+      k: safeKey(o.k) ?? `${category}:-`,
+      p: CATEGORIES[category].level,
+    } as const;
+    // A v2 body is read as its generic v1 alert until this app can decrypt.
+    return { ...base, v: 1 };
+  }
+  return buildPushPayload({ category });
+}
+
+const APP_PATHS = [
+  /^\/needs$/,
+  /^\/machines$/,
+  /^\/session\/[A-Za-z0-9_-]{1,64}$/,
+  /^\/task\/[A-Za-z0-9_-]{1,64}$/,
+  /^\/orchestrator\?workspaceId=[A-Za-z0-9_-]{1,64}$/,
+];
+
+/** True for a link the registry could have produced. */
+export function isAppLink(link: string): boolean {
+  return APP_PATHS.some((re) => re.test(link));
+}
+
+/**
+ * True only for a payload the registry could have built: fixed title, the
+ * category's own word, a known link shape, a plain key. A sender checks this
+ * before it sends, so nothing else can leave the machine.
+ */
+export function isGenericPayload(p: unknown): p is PushEnvelopeV1 {
+  if (!p || typeof p !== "object") return false;
+  const o = p as Record<string, unknown>;
+  if (o.v !== 1 || !isPushCategory(o.c)) return false;
+  const def = CATEGORIES[o.c];
+  return (
+    Object.keys(o).sort().join() === "b,c,k,l,p,t,v" &&
+    o.t === PUSH_TITLE &&
+    o.b === def.word &&
+    o.p === def.level &&
+    typeof o.l === "string" &&
+    isAppLink(o.l) &&
+    safeKey(o.k) === o.k
+  );
+}

package/lib/notify/index.ts

@@ -9,6 +9,9 @@ import { db, type Session } from "../db";
 import { Limiter, type Outcome } from "./limiter";
 import { holdForBatch, msToNextSweep } from "../away/state";
 import { selectNotifier, type TelegramConfig } from "./notifiers";
+import { pushAvailable, pushEvent } from "./push";
+import { setFallbackSink } from "./push/sender";
+import type { PushCategory } from "./push-types";
 
 export type { Outcome } from "./limiter";
 
@@ -99,6 +102,23 @@ export function resumePhoneOutbox(): void {
   }
 }
 
+// Held text that push couldn't deliver goes to Telegram once.
+setFallbackSink(async (source, text) => {
+  const outcome = await limiter().push(source, text);
+  if (outcome.state === "failed") throw new Error(outcome.why);
+});
+
+// Which phone-app category a message belongs to. A message with one goes to
+// a registered device instead of Telegram, and to Telegram if push is off.
+export interface PushRoute {
+  category: PushCategory;
+  id?: string | null;
+  key?: string | null;
+  collapse?: string | null;
+  /** The session it is about, so a mirror of another machine's never pushes. */
+  sessionId?: string | null;
+}
+
 export class NotConfigured extends Error {
   constructor() {
     super(
@@ -111,10 +131,21 @@ export class NotConfigured extends Error {
 // NotConfigured when nothing would send it.
 export async function sendPhone(
   source: string,
-  text: string
+  text: string,
+  push?: PushRoute
 ): Promise<Outcome> {
   const body = text.trim();
   if (!body) throw new Error("Nothing to send");
+  if (push && pushAvailable()) {
+    const { sessionId, ...event } = push;
+    const out = await pushEvent(event, {
+      sessionId,
+      fallback: { source, text: body },
+    });
+    if (out === "queued") return { state: "pushed" };
+    if (out === "folded") return { state: "held", inMs: msToNextSweep() };
+    if (out === "dropped" || out === "muted") return { state: "skipped" };
+  }
   if (!selectNotifier(process.env, telegramConfig())) throw new NotConfigured();
   const outcome = await limiter().push(source, body);
   if (outcome.state === "failed")
@@ -142,15 +173,23 @@ export async function notifyFrom(
     holdForBatch(session.workspace_id, session.id, body)
   )
     return { state: "held", inMs: msToNextSweep() };
-  return sendPhone(
-    session ? `session:${session.id}` : "cli",
-    session ? `${session.name}: ${body}` : body
-  );
+  const source = session ? `session:${session.id}` : "cli";
+  return sendPhone(source, session ? `${session.name}: ${body}` : body, {
+    category: "agents",
+    id: session?.id,
+    key: `agents:${session?.id ?? "cli"}:${Date.now()}`,
+    collapse: `agents:${session?.id ?? "cli"}`,
+    sessionId: session?.id,
+  });
 }
 
 // For the server's own alerts: never throws, never waits on the send.
-export function notifyPhone(source: string, text: string): void {
-  sendPhone(source, text).catch((error) => {
+export function notifyPhone(
+  source: string,
+  text: string,
+  push?: PushRoute
+): void {
+  sendPhone(source, text, push).catch((error) => {
     if (!(error instanceof NotConfigured))
       console.error(
         `[notify] ${source}:`,

package/lib/notify/limiter.ts

@@ -16,7 +16,12 @@ export type Outcome =
   | { state: "held"; inMs: number }
   | { state: "duplicate" }
   | { state: "dropped" }
-  | { state: "failed"; why: string };
+  | { state: "failed"; why: string }
+  // Went to the phone app; Telegram only steps in if that fails.
+  | { state: "pushed" }
+  // Push had nothing to do: the device turned the category off, or Saad is
+  // at the Mac.
+  | { state: "skipped" };
 
 export function collapse(texts: string[]): string {
   if (texts.length === 1) return texts[0];

package/lib/notify/push/encode.ts

@@ -0,0 +1,42 @@
+/**
+ * The one place an event becomes the bytes the relay is given. v1 is the
+ * generic, content-free envelope. Encrypted rich text (v2) replaces the body
+ * of this function and nothing else: callers hand over an event, never a
+ * payload.
+ */
+
+import crypto from "crypto";
+import { buildPushPayload, isGenericPayload } from "../copy";
+import type { PushEnvelope, PushEvent, PushLevel } from "../push-types";
+
+export interface EncodedPush {
+  payload: PushEnvelope;
+  level: PushLevel;
+  priority: 10 | 5;
+  /** Opaque: a hash, so the relay and Apple learn nothing from it. */
+  collapseId: string;
+  threadId: string;
+}
+
+/** Same event key, same id, on every machine that sends it. */
+export const collapseId = (key: string) =>
+  crypto.createHash("sha256").update(key).digest("hex").slice(0, 32);
+
+export function encodePush(
+  event: PushEvent,
+  _device?: { id: string }
+): EncodedPush {
+  const payload = buildPushPayload({ ...event, key: null });
+  // Nothing but what the registry could have built may leave the machine.
+  if (!isGenericPayload(payload))
+    throw new Error(
+      "refusing to send a push payload the registry didn't build"
+    );
+  return {
+    payload,
+    level: payload.p,
+    priority: payload.p === "passive" ? 5 : 10,
+    collapseId: collapseId(event.collapse ?? event.key ?? payload.k),
+    threadId: event.category,
+  };
+}

package/lib/notify/push/events.ts

@@ -0,0 +1,72 @@
+/**
+ * One helper per event that can reach the phone. Each is fire-and-forget:
+ * a failure here must never touch the code that raised the event.
+ */
+
+import { db } from "../../db";
+import { pushEvent } from "./index";
+import type { PushEvent } from "../push-types";
+
+function fire(event: PushEvent, sessionId?: string | null): void {
+  pushEvent(event, { sessionId }).catch((error) =>
+    console.error(
+      `[push] ${event.category}:`,
+      error instanceof Error ? error.message : error
+    )
+  );
+}
+
+export const pushAskRaised = (askId: number, workspaceId: string) =>
+  fire({ category: "asks", id: workspaceId, key: `ask:${askId}` });
+
+export const pushNeedsYou = (sessionId: string, armedAt: number) =>
+  fire(
+    {
+      category: "needs-you",
+      id: sessionId,
+      key: `needs-you:${sessionId}:${armedAt}`,
+      collapse: `needs-you:${sessionId}`,
+    },
+    sessionId
+  );
+
+const forTask = (
+  category: "review" | "ci" | "merged",
+  prefix: string,
+  taskId: string,
+  sha?: string | null
+) =>
+  fire(
+    {
+      category,
+      id: taskId,
+      key: `${prefix}:${taskId}${sha ? `:${sha}` : ""}`,
+      collapse: `task:${taskId}`,
+    },
+    taskId
+  );
+
+export const pushReviewReady = (taskId: string, sha: string) =>
+  forTask("review", "review", taskId, sha);
+export const pushCiFailed = (taskId: string, sha: string) =>
+  forTask("ci", "ci", taskId, sha);
+export const pushReviewBlocked = (taskId: string, sha: string) =>
+  forTask("ci", "review-block", taskId, sha);
+export const pushMerged = (taskId: string) =>
+  forTask("merged", "merged", taskId);
+
+export const pushPlanReady = (sessionId: string, itemId: string) => {
+  // Only a task has a screen to open; a plain chat's plan goes to the list.
+  const task = db
+    .prepare(`SELECT task_status FROM sessions WHERE id = ?`)
+    .get(sessionId) as { task_status: string | null } | undefined;
+  fire(
+    {
+      category: "review",
+      id: task?.task_status ? sessionId : null,
+      key: `plan:${sessionId}:${itemId}`,
+      collapse: `plan:${sessionId}`,
+    },
+    sessionId
+  );
+};

package/lib/notify/push/index.ts

@@ -0,0 +1,183 @@
+/**
+ * Push for the phone app. `pushEvent` decides whether an event goes out, to
+ * whom, and now or in the Away digest; the sender does the delivering.
+ * Telegram is the fallback only for what Telegram carried before push
+ * (events given a `fallback`); the newer events are push-only.
+ */
+
+import crypto from "crypto";
+import { db } from "../../db";
+import { activeAway } from "../../away/state";
+import { listPushDevices } from "@/lib/security/devices";
+import type { PushEvent } from "../push-types";
+import { encodePush } from "./encode";
+import * as outbox from "./outbox";
+import { atMac } from "./presence";
+import {
+  CAP_PER_HOUR,
+  HOUR_MS,
+  capExempt,
+  foldsWhenAway,
+  presenceGated,
+} from "./policy";
+import { linked, NOT_LINKED } from "./relay";
+import { PushSender } from "./sender";
+
+const g = globalThis as unknown as { __agentosPush?: PushSender };
+
+export function sender(): PushSender {
+  return (g.__agentosPush ??= new PushSender());
+}
+
+/** Whether a message with a push category can go by push right now. */
+export function pushAvailable(): boolean {
+  return linked() && !sender().unavailable() && listPushDevices().length > 0;
+}
+
+export function pushStatus(): { linked: boolean; unavailable: string | null } {
+  return { linked: linked(), unavailable: sender().unavailable() };
+}
+
+export type PushOutcome =
+  | "queued"
+  | "folded"
+  | "dropped"
+  | "muted"
+  | "unavailable";
+
+export interface PushOptions {
+  /** Held text that goes by Telegram if no phone is reached. */
+  fallback?: { source: string; text: string } | null;
+  /** A session the event is about: a mirror of another machine's never pushes. */
+  sessionId?: string | null;
+  /** Explicit sends (a test): no presence, Away, cap or category rules. */
+  bypass?: boolean;
+  deviceIds?: string[];
+}
+
+function isMirrored(sessionId: string): boolean {
+  const s = db
+    .prepare(`SELECT host_id, peer_mirror FROM sessions WHERE id = ?`)
+    .get(sessionId) as
+    | { host_id: string | null; peer_mirror: number | null }
+    | undefined;
+  return !!s && (!!s.peer_mirror || (!!s.host_id && s.host_id !== "local"));
+}
+
+export async function pushEvent(
+  event: PushEvent,
+  opts: PushOptions = {}
+): Promise<PushOutcome> {
+  if (opts.sessionId && isMirrored(opts.sessionId)) return "dropped";
+  const s = sender();
+  if (!linked() || s.unavailable()) return "unavailable";
+  const devices = listPushDevices().filter(
+    (d) => !opts.deviceIds || opts.deviceIds.includes(d.id)
+  );
+  if (!devices.length) return "unavailable";
+  const targets = opts.bypass
+    ? devices
+    : devices.filter((d) => d.push.categories.includes(event.category));
+  if (!targets.length) return "muted";
+
+  const now = Date.now();
+  const key = event.key ?? `${event.category}:${event.id ?? "-"}:${now}`;
+  const enc = encodePush({ ...event, key });
+  const row = {
+    eventKey: key,
+    category: event.category,
+    level: enc.level,
+    payload: enc.payload,
+    collapseId: enc.collapseId,
+    now,
+  };
+  if (!opts.bypass) {
+    if (activeAway() && foldsWhenAway(event.category)) {
+      outbox.enqueue({ ...row, deviceId: "", state: "folded" });
+      return "folded";
+    }
+    if (presenceGated(event.category) && (await atMac())) return "dropped";
+  }
+  let queued = 0;
+  for (const d of targets) {
+    const over =
+      !opts.bypass &&
+      !capExempt(event.category) &&
+      enc.level !== "passive" &&
+      outbox.alertingSince(d.id, now) >= CAP_PER_HOUR;
+    if (over) {
+      outbox.enqueue({ ...row, deviceId: d.id, state: "capped" });
+      // One summary an hour says there was more.
+      const sum = encodePush({
+        category: "digest",
+        key: `overflow:${d.id}:${Math.floor(now / HOUR_MS)}`,
+      });
+      outbox.enqueue({
+        eventKey: `overflow:${d.id}:${Math.floor(now / HOUR_MS)}`,
+        deviceId: d.id,
+        category: "digest",
+        level: sum.level,
+        payload: sum.payload,
+        collapseId: sum.collapseId,
+        now,
+      });
+      queued++;
+      continue;
+    }
+    if (outbox.enqueue({ ...row, deviceId: d.id, fallback: opts.fallback }))
+      queued++;
+  }
+  if (queued) void s.kick();
+  return queued ? "queued" : "dropped";
+}
+
+export interface TestResult {
+  deviceId: string;
+  status: "sent" | "gone" | "failed";
+  error: string | null;
+}
+
+/** A real send to the phones now, ignoring every quiet rule, and its answer. */
+export async function sendTestPush(
+  deviceId?: string
+): Promise<{ results: TestResult[]; unavailable: string | null }> {
+  const s = sender();
+  if (!linked()) return { results: [], unavailable: NOT_LINKED };
+  s.clearUnavailable();
+  const key = `test:${Date.now()}:${crypto.randomBytes(3).toString("hex")}`;
+  const devices = listPushDevices().filter(
+    (d) => !deviceId || d.id === deviceId
+  );
+  const enc = encodePush({ category: "system", key });
+  const now = Date.now();
+  for (const d of devices)
+    outbox.enqueue({
+      eventKey: key,
+      deviceId: d.id,
+      category: "system",
+      level: enc.level,
+      payload: enc.payload,
+      collapseId: enc.collapseId,
+      now,
+    });
+  await s.kick();
+  const results = outbox.rowsFor(key).map((r) => ({
+    deviceId: r.device_id,
+    status: (r.state === "sent"
+      ? "sent"
+      : r.state === "gone"
+        ? "gone"
+        : "failed") as TestResult["status"],
+    error: r.state === "sent" ? null : (r.error ?? "not sent"),
+  }));
+  return { results, unavailable: s.unavailable() };
+}
+
+export function resumePushOutbox(): void {
+  sender().resume();
+}
+
+/** How many held events the next Away digest stands for. */
+export function takeFoldedPushes(now = Date.now()): number {
+  return outbox.takeFolded(now);
+}