agentus 0.0.0-stage → 0.1.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,
+  };
+}