agentus 0.0.0-stage → 0.2.0

package/packages/server/src/notify/types.ts

@@ -0,0 +1,222 @@
+// Notify contract v0.1 — the wire types shared by the Agentus server and the
+// Android companion app. See docs/android-notify-contract.md at the workspace root
+// (tasks/20261001-agentus/android-notify-contract.md) for the rationale.
+//
+// Rule of the contract: this file only ever GROWS. Adding a field is compatible;
+// changing the meaning of an existing one is not. A device that does not know a
+// field ignores it, and the server decides what to send from `capabilities`,
+// never from a version number.
+
+export type NotifyPlatform = "android" | "ios" | "web";
+
+/** Device -> server handshake, sent once at pairing. */
+export interface DeviceCapabilities {
+  platform: NotifyPlatform;
+  /** Android API level (36+ = Live Updates are possible). */
+  sdkInt: number;
+  appVersion: string;
+  /** Highest contract schema the app understands. */
+  schema: number;
+  /** Feature switches: live_update | progress | actions | remote_input | icon_url | channels | deeplink */
+  capabilities: string[];
+}
+
+export interface NotifyDevice extends DeviceCapabilities {
+  deviceId: string;
+  name: string;
+  /** Device bearer token (issued at pairing; stored in the app's Keystore). */
+  token: string;
+  createdAt: number;
+  lastSeenAt: number | null;
+  /** Highest activity seq this device has acknowledged (replay anchor). */
+  cursor: number;
+  /**
+   * The device reporting on itself — last report wins. Contains the app version, the ROM's
+   * focus-protocol generation, the exact island payload it would attach and whether it holds the
+   * microphone. Written by POST /api/notify/diag: the phone writes the answer down where the server
+   * can read it, which is the only way to diagnose a device that cannot be plugged into anything.
+   */
+  diag?: { at: number; text: string } | null;
+}
+
+/** Server -> device, one notification. `ref` never leaves the server. */
+export interface NotifyRef {
+  /** Handler family: "permission" | "open" | "stop" | ... — the server's switch. */
+  type: string;
+  [key: string]: unknown;
+}
+
+export type NotifyOp = "upsert" | "dismiss" | "clear_all" | "probe";
+
+export type ActionStyle = "primary" | "danger" | "default";
+
+export interface ActivityAction {
+  id: string;
+  label: string;
+  style?: ActionStyle;
+}
+
+export interface ActivityProgressSegment {
+  length: number;
+  color?: string;
+}
+
+export interface ActivityProgressPoint {
+  position: number;
+  color?: string;
+}
+
+/** Progress. `segments`/`points` feed Android 16 Notification.ProgressStyle;
+ *  a device without `progress` support falls back to a plain notification. */
+export interface ActivityProgress {
+  value?: number | null;
+  indeterminate?: boolean;
+  styledByProgress?: boolean;
+  segments?: ActivityProgressSegment[];
+  points?: ActivityProgressPoint[];
+  /** Android drawable name already bundled in the app ("icon:name" convention). */
+  trackerIcon?: string;
+  startIcon?: string;
+  endIcon?: string;
+}
+
+/** The server defines channels, the app creates them on demand — that way
+ *  importance/sound/vibration are server-controlled and never need a new APK. */
+export interface ChannelSpec {
+  id: string;
+  name: string;
+  importance?: "min" | "low" | "default" | "high";
+  sound?: boolean;
+  vibration?: boolean;
+  /** The server took the sound away for a reason of its own (today: a voice call is live, so a tone
+   *  would be recorded by the agent's own microphone). Behavioural, not cosmetic: an Android channel's
+   *  sound/importance cannot be changed after creation, so a muted frame must be routed to a quiet
+   *  channel rather than an updated one. */
+  muted?: boolean;
+}
+
+export interface ActivityInput {
+  enabled: boolean;
+  placeholder?: string;
+}
+
+export interface ActivityObject {
+  schema: 1;
+  op: NotifyOp;
+  /** Stable id: one id = one notification slot. */
+  activityId: string;
+  /** Monotonic per activity; a device drops anything older than what it holds. */
+  revision: number;
+  /** Semantic label ("agent_running" | "approval" | "agent_done" | "error"). */
+  kind?: string;
+  priority?: "high" | "default" | "low";
+  /** Ongoing is a precondition for a promoted Live Update. */
+  ongoing?: boolean;
+  /** The server's wish; the app promotes only if the device/user allows it. */
+  promotable?: boolean;
+  /** Which promotion path this frame must take, for testing the two island APIs apart:
+   *  absent/"" = the app's order (vendor island first, AOSP Live Update after),
+   *  "xiaomi" = the vendor island only, "aosp" = Android 16's own Live Update only.
+   *  Behavioural, not cosmetic: it is how "does HyperOS 3 render Android's own chip at all"
+   *  becomes a button instead of another APK. */
+  path?: string;
+  title: string;
+  subtitle?: string | null;
+  body?: string | null;
+  progress?: ActivityProgress | null;
+  /** Large icon, fetched by the app (server-controlled visuals). */
+  iconUrl?: string | null;
+  /** Small (status bar) icon — must be a drawable already inside the APK. */
+  smallIcon?: string | null;
+  channel?: ChannelSpec | null;
+  visibility?: "public" | "private" | "secret";
+  actions?: ActivityAction[];
+  input?: ActivityInput | null;
+  /** Where tapping the notification goes (web UI path).
+   *  @deprecated superseded by `open` — still emitted so an app built before the `open` contract keeps
+   *  a working tap. Remove once no such app is in the field. */
+  deeplink?: string | null;
+  /** Where a tap goes, in the abstract: a URL plus how strongly the sender wants it opened in an app.
+   *
+   *  The split is deliberate. The SENDER knows the destination; only the RECEIVER knows what is
+   *  installed and which origins it trusts, so `prefer` is a hint and the device keeps the policy
+   *  (see docs/android-notify-contract.md §5.2). This is also what lets a third party push a
+   *  notification through the same contract: a sender that knows nothing about Agentus sends
+   *  `{ url, prefer: "web" }` and gets a plain link, while our own server asks for its cockpit. */
+  open?: OpenTarget | null;
+  staleAt?: number;
+  expiresAt?: number;
+}
+
+/** How to open an activity when it is tapped. */
+export interface OpenTarget {
+  /** Absolute, or relative to the server the activity arrived from (a self-hosted server may not know
+   *  its own public address — it sits behind a tunnel — so the receiver resolves the rest). */
+  url: string;
+  /** `app` = the sender asserts an app on this device handles the URL (our cockpit); `web` = always
+   *  hand it to the platform's web handler; `auto` (default) = the receiver's own rule, which is
+   *  "in-app if the origin is one of my servers, otherwise the browser". A receiver must never
+   *  navigate its own authenticated UI to a foreign origin on a payload's say-so. */
+  prefer?: "app" | "web" | "auto";
+}
+
+/** Device -> server: the operator pressed something on a notification. */
+export interface ActionCallback {
+  deviceId: string;
+  activityId: string;
+  revision: number;
+  actionId: string;
+  input?: string | null;
+  ts: number;
+  nonce?: string;
+}
+
+/** Server -> device WS frames. */
+export type NotifyFrame =
+  | { t: "hello"; deviceId: string; serverTime: number; cursor: number; live: boolean }
+  | { t: "activity"; seq: number; activity: ActivityObject }
+  | { t: "bye"; reason: string };
+
+/** Server-side record: what was published + how to interpret its actions. */
+export interface ActivityRecord {
+  seq: number;
+  activity: ActivityObject;
+  /** Per-action handler refs, keyed by action id. Never sent to a device. */
+  actionRefs: Record<string, NotifyRef>;
+  publishedAt: number;
+}
+
+/**
+ * What the phone is allowed to be told. These are the operator's switches, not the app's:
+ * the app is a generic renderer, so "do I want a notification for this" is a server-side
+ * decision that must be changeable without shipping a new APK.
+ */
+export interface NotifyRules {
+  /** A turn started (the ongoing "running" card). */
+  turnStart: boolean;
+  /** The agent is waiting for an approval — the one you answer from the lock screen. */
+  approval: boolean;
+  /** A turn ended (done / failed). */
+  completion: boolean;
+  /** Do not push while the operator is looking at that very session in the cockpit. */
+  quietWhenWatching: boolean;
+}
+
+export const DEFAULT_NOTIFY_RULES: NotifyRules = {
+  turnStart: true,
+  approval: true,
+  completion: true,
+  quietWhenWatching: true,
+};
+
+/** Which session the cockpit is showing right now (in-memory only — presence is ephemeral). */
+export interface Presence {
+  sessionId: string | null;
+  visible: boolean;
+  /** The operator is on a VOICE CALL with `sessionId` right now (page-reported, same TTL). A call is
+   *  strictly more than "watching": the call is already reading the replies aloud, and its capture is a
+   *  plain AudioRecord with no echo cancellation — so any notification tone lands in the agent's own
+   *  microphone. While a call is live nothing may make a sound (see the center's `onCall`). */
+  call?: boolean;
+  at: number;
+}

package/packages/server/src/plan/plan.ts

@@ -0,0 +1,126 @@
+/**
+ * Plan semantics, in one place.
+ *
+ * ACP plan frames are whole-list snapshots (`plan` in v1 = replace semantics), and an agent's own
+ * todo state dies with its PROCESS — which is why a plan used to vanish from the cockpit after a
+ * restart (`tasks/20261001-agentus/design-plan-service.md` §1 has the forensics). So the server owns
+ * the plan object (Store's `plans` table) and every writer funnels through here, so that they agree
+ * on two things:
+ *
+ *   · NORMALISATION — the item shape the card renders. Unknown statuses pass through on purpose:
+ *     ACP v2 adds `cancelled` and reserves `_`-prefixed unknowns, and a client that drops what it
+ *     does not understand renders a plan that is quietly wrong.
+ *   · the TURN LIFECYCLE rules — only the run closes a plan, never the agent (Studio's rule). A
+ *     leftover `in_progress` step is demoted to `pending` (nothing is running it anymore) and the
+ *     snapshot carries an honest terminal stamp.
+ */
+import type { PlanItem } from "../../../shared/src/index.js";
+
+/** Studio caps its plan remark at 1000 chars; take the same bound rather than invent one. */
+export const MAX_EXPLANATION = 1000;
+
+export type PlanTerminal = "ended" | "interrupted" | "failed";
+export type PlanSource = "acp" | "mcp" | "server";
+
+/** Coerce whatever a writer sent (agent frame, MCP tool) into what the card renders. */
+export function normalizeItems(raw: unknown): PlanItem[] {
+  if (!Array.isArray(raw)) return [];
+  const out: PlanItem[] = [];
+  for (const entry of raw) {
+    if (!entry || typeof entry !== "object") continue;
+    const e = entry as Record<string, unknown>;
+    const content = String(e.content ?? "").trim();
+    if (!content) continue;
+    const item: PlanItem = {
+      content,
+      // An entry with no status is not "completed" and not "in_progress": it is something the
+      // agent listed and has not said anything else about.
+      status: typeof e.status === "string" && e.status ? e.status : "pending",
+    };
+    if (typeof e.priority === "string" && e.priority) item.priority = e.priority;
+    out.push(item);
+  }
+  return out;
+}
+
+/** Anything the run still owes the operator. `completed`/`cancelled` are closed; an UNKNOWN status
+ *  counts as unfinished — a step we cannot interpret should not be reported as done. */
+export function hasUnfinished(items: PlanItem[]): boolean {
+  return items.some((i) => i.status !== "completed" && i.status !== "cancelled");
+}
+
+/** Demote steps that cannot still be running, because the run that owned them is over. */
+export function demoteInProgress(items: PlanItem[]): PlanItem[] {
+  return items.map((i) => (i.status === "in_progress" ? { ...i, status: "pending" } : i));
+}
+
+/** Studio's bound and Studio's tolerance: a non-string is dropped, not stringified. */
+export function clampExplanation(raw: unknown): string | null {
+  if (typeof raw !== "string") return null;
+  const s = raw.trim();
+  if (!s) return null;
+  return s.length > MAX_EXPLANATION ? s.slice(0, MAX_EXPLANATION) : s;
+}
+
+/** One writer per session — and it is the AGENT's, whenever it has something to say.
+ *
+ *  Both channels can exist for the same session, and two writers means two plans racing on one card.
+ *  The rule is not "whoever typed first" but *native priority*: a frame is the agent's own plan, so
+ *  it is NEVER refused — it takes the card over from a tool-written plan — and once a frame has
+ *  landed, `current` is "acp" and the tool is refused from then on. Failures land in the visible
+ *  direction: the plan on screen is the agent's.
+ *
+ *  Since every backend is MCP-driven by default, `incoming: "acp"` is now only ever seen from a row
+ *  that opted back into frames (session-manager's `#framesAccepted` drops the rest at the door), so
+ *  this is a backstop rather than the everyday path. */
+export function acceptsWriteFrom(current: PlanSource | undefined, incoming: PlanSource): boolean {
+  if (incoming === "acp") return true; // the agent's own channel outranks any tool
+  if (incoming === "server") return true; // the turn lifecycle is not a competing writer
+  if (!current || current === "server") return true;
+  return current === incoming;
+}
+
+/** Whether the plan TOOL may write this session's plan.
+ *
+ *  The comparison above is between the object's STORED source and the incoming one, and on an
+ *  MCP-driven row that is the wrong yardstick: the agent's frames are dropped at the door, so the
+ *  tool is the only writer the session has, and it must be able to take over a plan that an older
+ *  build wrote from frames. Judging by the stored source alone strands exactly those sessions — the
+ *  card keeps pre-flip content that nothing can update, and the tool answers "the frames wrote this"
+ *  about frames the cockpit is now ignoring.
+ *
+ *  A row that opted back into `acp` keeps the old ranking: its frames win, the tool is refused. */
+export function acceptsToolWrite(current: PlanSource | undefined, rowRendersFrames: boolean): boolean {
+  if (!rowRendersFrames) return true;
+  return acceptsWriteFrom(current, "mcp");
+}
+
+/** ACP v2's plan updates (`session/update` → `plan_update`), behind an experiment switch.
+ *
+ *  v2 is still a draft: the SDK ships it under an experimental subpath and both ends of this wire
+ *  declare protocolVersion 1, so NOTHING may depend on it yet. Parsing it anyway costs one branch,
+ *  and it buys the property that matters for a draft schema — a client that ignores a frame it does
+ *  not understand renders a plan that is quietly wrong. Off unless asked for: an experiment switch,
+ *  not a feature flag. */
+export function v2PlanEnabled(env: NodeJS.ProcessEnv = process.env): boolean {
+  return env.AGENTUS_ACP_V2_PLAN === "1";
+}
+
+/** Fold a v2 `plan_update` payload back into the v1 frame shape, or null when it carries nothing a
+ *  step list can render.
+ *
+ *  v2 wraps the entries one level deeper (`plan: { planId, type: "items", entries }`) and allows
+ *  two other content kinds — `markdown` and `file` — which are NOT step lists; guessing a list out
+ *  of them would put words on the card the agent never wrote as steps. It also allows several plans
+ *  per session (`planId`), which is why the id is returned rather than ignored: the caller decides
+ *  what to do with a second one. Kept pure (and exported) so the mapping can be unit-tested against
+ *  the draft schema without a server. */
+export function foldPlanUpdate(update: Record<string, unknown>): { entries: PlanItem[]; planId: string; meta: unknown } | null {
+  const plan = (update?.plan ?? null) as { planId?: unknown; type?: unknown; entries?: unknown } | null;
+  if (!plan || plan.type !== "items") return null;
+  return {
+    entries: normalizeItems(plan.entries),
+    planId: String(plan.planId ?? ""),
+    meta: update._meta ?? null,
+  };
+}

package/packages/server/src/pty-helper.py

@@ -0,0 +1,135 @@
+#!/usr/bin/env python3
+"""Run one command on a REAL pseudo-terminal and shovel bytes between it and stdio.
+
+This is the whole trick behind a web terminal (ttyd does the same thing in C): `forkpty` gives the
+child a controlling terminal, so the shell believes a human is at the keyboard — line editing,
+prompts, colours, job control, full-screen programs (vim, top) all work. Without it (pipe stdio)
+the shell is in non-interactive mode: no prompt on screen, no echo, no cursor, SIGWINCH meaningless,
+and any terminal emulator in front of it is a lie.
+
+Why a Python helper instead of node-pty: node-pty is a build-time native module and this project
+stays dependency-free on install. Python 3 is present on macOS and essentially every Linux; its
+stdlib already has forkpty + termios, which is all a PTY needs. If python3 is missing the server
+falls back to pipes and says so in the panel.
+
+Wire format, all raw bytes:
+    stdin  (fd 0)  -> keystrokes from the browser, written straight to the PTY master
+    stdout (fd 1)  <- everything the PTY produces, written straight out (no filtering, no ANSI
+                      stripping: a terminal emulator consumes the escape sequences, a <pre> cannot)
+    fd 3           <- control channel, one command per line: "resize <cols> <rows>"
+
+Sizing: the initial size comes from AGENTUS_PTY_COLS / AGENTUS_PTY_ROWS, and `resize` applies
+TIOCSWINSZ to the master — the kernel then signals the child's foreground process group (SIGWINCH),
+which is what makes vim redraw at the new width.
+
+Exit: when the child exits we exit with its status; when stdin hits EOF (the socket closed) or we
+are signalled, we kill the child's process group first so no shell is orphaned.
+"""
+import errno
+import fcntl
+import os
+import pty
+import select
+import signal
+import struct
+import sys
+import termios
+
+CTL_FD = 3
+
+
+def set_winsize(fd: int, cols: int, rows: int) -> None:
+    cols = max(1, min(cols, 1000))
+    rows = max(1, min(rows, 1000))
+    fcntl.ioctl(fd, termios.TIOCSWINSZ, struct.pack("HHHH", rows, cols, 0, 0))
+
+
+def main() -> int:
+    argv = sys.argv[1:] or [os.environ.get("SHELL") or "/bin/sh"]
+    try:
+        cols = int(os.environ.get("AGENTUS_PTY_COLS") or 80)
+        rows = int(os.environ.get("AGENTUS_PTY_ROWS") or 24)
+    except ValueError:
+        cols, rows = 80, 24
+
+    pid, master = pty.fork()
+    if pid == 0:  # child: this IS the shell now
+        os.environ["TERM"] = os.environ.get("TERM") or "xterm-256color"
+        try:
+            os.execvp(argv[0], argv)
+        except Exception as exc:  # noqa: BLE001 - report it on the terminal rather than dying mute
+            os.write(2, f"cannot start {argv[0]}: {exc}\r\n".encode())
+            os._exit(127)
+
+    set_winsize(master, cols, rows)
+
+    ctl = None
+    try:
+        ctl = os.fdopen(CTL_FD, "r", buffering=1)
+    except OSError:
+        ctl = None  # no control channel: a fixed-size terminal is still a terminal
+
+    stdin_fd = 0
+    running = True
+    while running:
+        watch = [master, stdin_fd] + ([CTL_FD] if ctl else [])
+        try:
+            ready, _, _ = select.select(watch, [], [])
+        except OSError as exc:
+            if exc.errno == errno.EINTR:
+                continue
+            break
+
+        if master in ready:
+            try:
+                data = os.read(master, 65536)
+            except OSError:
+                data = b""
+            if not data:
+                break  # the child closed the pty: it is gone
+            os.write(1, data)
+
+        if stdin_fd in ready:
+            try:
+                data = os.read(stdin_fd, 65536)
+            except OSError:
+                data = b""
+            if not data:
+                break  # EOF: the browser went away, take the shell with us
+            os.write(master, data)
+
+        if ctl and CTL_FD in ready:
+            line = ctl.readline()
+            if line == "":
+                ctl.close()
+                ctl = None
+                continue
+            parts = line.split()
+            if parts and parts[0] == "resize" and len(parts) == 3 and parts[1].isdigit() and parts[2].isdigit():
+                set_winsize(master, int(parts[1]), int(parts[2]))
+
+    # Reap the child, then leave with its status so the server can report a real exit code.
+    status = 0
+    try:
+        _, raw = os.waitpid(pid, 0)
+        status = os.waitstatus_to_exitcode(raw) if hasattr(os, "waitstatus_to_exitcode") else 0
+    except ChildProcessError:
+        pass
+    except KeyboardInterrupt:
+        pass
+    return 0 if status is None else status
+
+
+def _terminate(_signum, _frame):  # noqa: ANN001 - signal handler
+    # The server kills our process group; this is the polite path when only we are signalled.
+    try:
+        os.kill(0, signal.SIGKILL)
+    except OSError:
+        pass
+    raise SystemExit(0)
+
+
+if __name__ == "__main__":
+    signal.signal(signal.SIGTERM, _terminate)
+    signal.signal(signal.SIGHUP, _terminate)
+    sys.exit(main())