agentus 0.3.3 → 0.3.5

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

@@ -26,8 +26,10 @@ import type {
   NotifyFrame,
   NotifyRef,
   NotifyRules,
+  NotifyWebRules,
   Presence,
   OpenTarget,
+  WebNotice,
 } from "./types.js";
 
 export interface NotifyCenterOptions {
@@ -152,6 +154,8 @@ export class NotifyCenter {
   /** actionKey -> when it was consumed, so a button can only fire once. */
   private readonly consumed = new Map<string, number>();
   private onActionCb: ((e: ActionEvent) => void) | null = null;
+  /** The page channel's sink: index.ts fans this out to every cockpit websocket. */
+  private onNoticeCb: ((n: WebNotice) => void) | null = null;
   private timers: NodeJS.Timeout[] = [];
   private wss: WebSocketServer | null = null;
   /** Which session the cockpit is showing, and whether its tab is visible. Deliberately in
@@ -163,14 +167,34 @@ export class NotifyCenter {
 
   /** The operator's switches, always complete (a state file may predate them). */
   rules(): NotifyRules {
-    return { ...DEFAULT_NOTIFY_RULES, ...(this.state.rules ?? {}) };
+    // A state file written before the web channel existed has no `web` key at all, so the stored
+    // value is really partial — the cast says that out loud instead of pretending otherwise.
+    const stored = this.state.rules as Partial<NotifyRules> | undefined;
+    // `web` is merged one level deeper than the rest: a partial patch (one switch from the page) must
+    // not drop the other two — a nested object replaced wholesale is how a channel silently forgets
+    // its settings.
+    return {
+      ...DEFAULT_NOTIFY_RULES,
+      ...(stored ?? {}),
+      web: { ...DEFAULT_NOTIFY_RULES.web, ...(stored?.web ?? {}) },
+    };
   }
 
   setRules(patch: Partial<NotifyRules>): NotifyRules {
-    const next: NotifyRules = { ...this.rules(), ...patch };
+    const current = this.rules();
+    const next: NotifyRules = {
+      ...current,
+      ...patch,
+      web: { ...current.web, ...(patch.web ?? {}) },
+    };
     this.state.rules = next;
     this.save();
-    this.log(`[notify] rules turnStart=${next.turnStart} approval=${next.approval} completion=${next.completion} quietWhenWatching=${next.quietWhenWatching}`);
+    const w = next.web;
+    this.log(
+      `[notify] rules turnStart=${next.turnStart} approval=${next.approval} completion=${next.completion} ` +
+      `quietWhenWatching=${next.quietWhenWatching} | web enabled=${w.enabled} turnStart=${w.turnStart} ` +
+      `approval=${w.approval} completion=${w.completion}`,
+    );
     return next;
   }
 
@@ -473,6 +497,27 @@ export class NotifyCenter {
     return this.events.filter((e) => e.seq > cursor && e.activity.op !== "clear_all");
   }
 
+  // ---- the page channel (browser notifications) -----------------------------
+  //
+  // The same decision, a second renderer. Kept here (not in the page) so that strings, dedup and the
+  // card lifecycle have ONE owner: the page cannot re-derive "what happened" from the transcript, and
+  // a rule change must apply to both channels without shipping a bundle.
+  //
+  // What this channel deliberately does NOT do: consult presence. The page knows whether it is the
+  // tab in front (`document.hidden`) and stays quiet by itself, which is the same judgement made where
+  // the fact lives — and it must stay that way, because one browser tab cannot see the other machine.
+
+  onNotice(cb: (n: WebNotice) => void): void {
+    this.onNoticeCb = cb;
+  }
+
+  /** Emit one page notice, gated on the web channel's own switches. */
+  private notice(n: Omit<WebNotice, "at">, rule: keyof Omit<NotifyWebRules, "enabled">): void {
+    const web = this.rules().web;
+    if (!web.enabled || !web[rule]) return;
+    this.onNoticeCb?.({ ...n, at: Date.now() });
+  }
+
   // ---- actions -------------------------------------------------------------
 
   onAction(cb: (e: ActionEvent) => void): void {
@@ -927,11 +972,11 @@ export class NotifyCenter {
     const title = (sessionId: string): string => this.sessionTitle?.(sessionId) ?? sessionId.slice(0, 8);
     const link = (sessionId: string): string => `/?session=${encodeURIComponent(sessionId)}`;
     switch (evt.t) {
-      case "turn-start":
-        // The rules gate BEFORE anything else: an event that is switched off must not even be
-        // evaluated against presence (and a suppressed event must not be mistaken for a bug).
-        if (!this.rules().turnStart || this.watching(evt.sessionId)) return;
-        this.publish({
+      case "turn-start": {
+        // Rules gate the PHONE first, and that is why the page's copy is emitted before the gate: the
+        // two channels have independent switches, and an early return for one must not starve the
+        // other. Both render the SAME object, so the words can never drift apart.
+        const running: ActivityObject = {
           schema: 1, op: "upsert", activityId: `turn:${evt.sessionId}`, revision: this.nextRevision(`turn:${evt.sessionId}`),
           kind: "agent_running", priority: "low", ongoing: true, promotable: true,
           title: "Agentus · 运行中",
@@ -939,29 +984,55 @@ export class NotifyCenter {
           progress: { indeterminate: true },
           channel: { id: "agent_running", name: "任务运行中", importance: "low", sound: false },
           smallIcon: "agentus", ...tapTarget(link(evt.sessionId)), visibility: "public",
-        });
+        };
+        this.notice({
+          op: "upsert", noticeId: `turn:${evt.sessionId}`, kind: "agent_running",
+          // The browser card drops the `Agentus ·` prefix the phone title carries: a browser already
+          // shows the origin and the icon, so the product's own name would spend the visible line.
+          title: "运行中", body: running.body ?? "", open: link(evt.sessionId),
+        }, "turnStart");
+        if (!this.rules().turnStart || this.watching(evt.sessionId)) return;
+        this.publish(running);
         return;
-      case "permission":
+      }
+      case "permission": {
         // Never suppressed by presence: this is a decision waiting on a human, and the whole
         // point of the phone being in the loop is answering it while away from the desk.
+        const { activity, actionRefs } = this.approvalActivity(evt.request, title(evt.request.sessionId), link(evt.request.sessionId));
+        this.notice({
+          op: "upsert", noticeId: `perm:${evt.request.requestId}`, kind: "approval",
+          title: activity.title, body: activity.body ?? "", open: link(evt.request.sessionId),
+          // Sticky: a browser card that fades away while the agent is still blocked is the same
+          // failure as a dead button on a lock screen.
+          sticky: true,
+        }, "approval");
         if (!this.rules().approval) return;
-        this.publishApproval(evt.request, title(evt.request.sessionId), link(evt.request.sessionId));
+        this.publish(activity, { actionRefs });
         return;
+      }
       case "permission-resolved":
         // Always clear the card, even if the request itself was never published — a stale
-        // "waiting for you" on the phone is worse than no notification at all.
+        // "waiting for you" on the phone is worse than no notification at all. The page's card goes
+        // away for the same reason and with the same unconditionality — and it is NOT switch-gated:
+        // taking a dead card off the screen is not an interruption, and gating it on a preference
+        // would leave a card nobody can answer.
         this.dismiss(`perm:${evt.requestId}`);
+        this.onNoticeCb?.({
+          op: "dismiss", noticeId: `perm:${evt.requestId}`, kind: "approval", title: "", body: "", at: Date.now(),
+        });
         return;
       case "turn-end": {
         // The running card goes away unconditionally — a zombie "still running" on the phone is worse
         // than no card at all, even when the frame that started it was suppressed.
         this.dismiss(`turn:${evt.sessionId}`);
+        this.onNoticeCb?.({
+          op: "dismiss", noticeId: `turn:${evt.sessionId}`, kind: "agent_running", title: "", body: "", at: Date.now(),
+        });
         // Both gates belong here and both were missing: `completion` was stored but never read, and
         // presence was only consulted for turn-start — so the completion card fired while the operator was watching
         // the very session (and, mid-call, with a sound: the reported bug).
-        if (!this.rules().completion || this.watching(evt.sessionId)) return;
         const failed = Boolean(evt.error);
-        this.publish({
+        const done: ActivityObject = {
           schema: 1, op: "upsert", activityId: `done:${evt.sessionId}:${Date.now()}`, revision: 1,
           kind: failed ? "error" : "agent_done", priority: "high", ongoing: false, promotable: false,
           title: failed ? "执行失败" : "已完成",
@@ -974,10 +1045,23 @@ export class NotifyCenter {
           },
           actions: [{ id: "open", label: "查看", style: "primary" }],
           smallIcon: "agentus", ...tapTarget(link(evt.sessionId)), visibility: "private",
-        }, { actionRefs: { open: { type: "open", sessionId: evt.sessionId } } });
+        };
+        // The page's card is keyed per SESSION (`done:<id>`), unlike the phone's per-occurrence id:
+        // a browser card carries a `tag`, so one per session is what makes the newest replace the
+        // previous one instead of stacking a wall of 「已完成」. Nothing is lost — the transcript is
+        // the history; the card only has to say what just happened.
+        this.notice({
+          op: "upsert", noticeId: `done:${evt.sessionId}`, kind: failed ? "error" : "agent_done",
+          title: done.title, body: done.body ?? "", open: link(evt.sessionId),
+        }, "completion");
+        if (!this.rules().completion || this.watching(evt.sessionId)) return;
+        this.publish(done, { actionRefs: { open: { type: "open", sessionId: evt.sessionId } } });
         return;
       }
       case "error":
+        // Phone-only, on purpose. This is the cockpit's own error with no session in scope, and on a
+        // desktop it is already ON SCREEN — the page is drawing that error right now. A browser card
+        // repeating something the operator is looking at is the one thing this channel must not do.
         this.publish({
           schema: 1, op: "upsert", activityId: `error:${Date.now()}`, revision: 1, kind: "error",
           priority: "high", ongoing: false, promotable: false, title: "Agentus 报错",
@@ -991,7 +1075,12 @@ export class NotifyCenter {
     }
   }
 
-  private publishApproval(request: PermissionRequestView, sessionTitle: string, link: string): void {
+  /** The approval card, built but not published: the phone's activity and the page's notice are two
+   *  renderings of ONE object, so the wording lives here and nowhere else. */
+  private approvalActivity(request: PermissionRequestView, sessionTitle: string, link: string): {
+    activity: ActivityObject;
+    actionRefs: Record<string, NotifyRef>;
+  } {
     const actions = request.options.slice(0, 3).map((o) => ({
       id: o.optionId,
       label: o.name.slice(0, 24),
@@ -1006,15 +1095,18 @@ export class NotifyCenter {
       };
     }
     const tool = splitToolTitle(request.toolCallTitle);
-    this.publish({
-      schema: 1, op: "upsert", activityId: `perm:${request.requestId}`, revision: 1, kind: "approval",
-      priority: "high", ongoing: true, promotable: true,
-      title: tool.head ? `待你确认：${tool.head.slice(0, 60)}` : "待你确认",
-      body: nameAndDetail(sessionTitle, tool.target || request.kind),
-      channel: { id: "agent_approval", name: "权限请求", importance: "high", sound: true, vibration: true },
-      actions: actions.length ? actions : [{ id: "open", label: "查看", style: "primary" }],
-      input: { enabled: true, placeholder: "或直接回一句" },
-      smallIcon: "agentus", ...tapTarget(link), visibility: "private",
-    }, { actionRefs });
+    return {
+      activity: {
+        schema: 1, op: "upsert", activityId: `perm:${request.requestId}`, revision: 1, kind: "approval",
+        priority: "high", ongoing: true, promotable: true,
+        title: tool.head ? `待你确认：${tool.head.slice(0, 60)}` : "待你确认",
+        body: nameAndDetail(sessionTitle, tool.target || request.kind),
+        channel: { id: "agent_approval", name: "权限请求", importance: "high", sound: true, vibration: true },
+        actions: actions.length ? actions : [{ id: "open", label: "查看", style: "primary" }],
+        input: { enabled: true, placeholder: "或直接回一句" },
+        smallIcon: "agentus", ...tapTarget(link), visibility: "private",
+      },
+      actionRefs,
+    };
   }
 }

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

@@ -200,6 +200,21 @@ export interface NotifyRules {
   completion: boolean;
   /** Do not push while the operator is looking at that very session in the cockpit. */
   quietWhenWatching: boolean;
+  /** The OTHER channel: browser notifications on a machine that has the cockpit open. Same events,
+   *  rendered by the page (see WebNotice). Its own switches because the two channels are used in
+   *  different places: a "running" card belongs on a lock screen and is noise on a desktop that is
+   *  already showing the transcript, and a desktop has no `quietWhenWatching` need — the page knows
+   *  its own tab is in front and stays silent by itself. */
+  web: NotifyWebRules;
+}
+
+/** The web channel's own view of the same three events. */
+export interface NotifyWebRules {
+  /** The whole channel: off means the server sends pages nothing, whatever the per-kind switches say. */
+  enabled: boolean;
+  turnStart: boolean;
+  approval: boolean;
+  completion: boolean;
 }
 
 export const DEFAULT_NOTIFY_RULES: NotifyRules = {
@@ -207,8 +222,18 @@ export const DEFAULT_NOTIFY_RULES: NotifyRules = {
   approval: true,
   completion: true,
   quietWhenWatching: true,
+  // On by default, but only for the two events worth interrupting a desktop for: a decision waiting
+  // on a human, and a reply that finished while the tab was in the background.
+  web: { enabled: true, turnStart: false, approval: true, completion: true },
 };
 
+/**
+ * Server -> page: one browser notification. The type itself lives in `shared` (it is part of the
+ * browser protocol now — it rides the cockpit's websocket as `{t:"notify"}`), and is re-exported here
+ * so the notify centre keeps one import site.
+ */
+export type { WebNotice } from "../../../shared/src/index.js";
+
 /** Which session the cockpit is showing right now (in-memory only — presence is ephemeral). */
 export interface Presence {
   sessionId: string | null;

package/packages/server/src/settings.ts

@@ -102,10 +102,29 @@ export interface PrefsSettings {
   serverTts: boolean;
   /** which recogniser to use, when the caller does not force one */
   stt: "auto" | "browser" | "stream" | "server";
+  /** Whether — and how often — the cockpit tells the agent about the plan MCP it was handed.
+   *  The tool's own description says "prefer this over any todo tool", but on a runtime that
+   *  keeps MCP tools in a lazy-loaded catalog the agent never reads it unless it goes looking,
+   *  so the session's plan card stays empty while the agent keeps a todo list nobody can see.
+   *  A per-turn nudge in the prompt is what closes that last mile; this is its switch. */
+  planHint: PlanHintSettings;
+}
+
+export interface PlanHintSettings {
+  /** Inject the plan-tool hint at all. Off = the prompt carries the operator's words and
+   *  nothing else (some operators do not want anything appended to their message). */
+  on: boolean;
+  /** true = every turn (the agent is re-told as the plan moves); false = only the first prompt
+   *  of each agent process (a fresh process has no memory of the plan; a running one maintains
+   *  it itself, and re-sending it every turn costs context and invites re-deriving finished work). */
+  everyTurn: boolean;
 }
 
 export const PREFS_DEFAULT: PrefsSettings = {
   autoRead: false, voiceURI: "", rate: 1, lang: "", serverTts: false, stt: "auto",
+  // On by default: the feature exists because the tool was there and nobody used it. 仅首条 is
+  // the conservative default — it is also what the cockpit did before this was configurable.
+  planHint: { on: true, everyTurn: false },
 };
 
 export const CALL_DEFAULT: CallSettings = {
@@ -332,6 +351,12 @@ function pickPrefs(raw: unknown): PrefsSettings {
     const rate = Number(r.rate);
     if (Number.isFinite(rate) && rate >= 0.5 && rate <= 2) out.rate = rate;
     if (r.stt === "auto" || r.stt === "browser" || r.stt === "stream" || r.stt === "server") out.stt = r.stt;
+    const h = r.planHint;
+    if (h && typeof h === "object") {
+      const hr = h as Record<string, unknown>;
+      if (typeof hr.on === "boolean") out.planHint.on = hr.on;
+      if (typeof hr.everyTurn === "boolean") out.planHint.everyTurn = hr.everyTurn;
+    }
   }
   return out;
 }
@@ -512,6 +537,21 @@ export function savePrefs(patch: Record<string, unknown>): Settings {
     if (!["auto", "browser", "stream", "server"].includes(v)) throw new Error(`invalid stt: ${JSON.stringify(patch.stt)}`);
     next.stt = v as PrefsSettings["stt"];
   }
+  if ("planHint" in patch) {
+    const h = patch.planHint;
+    if (!h || typeof h !== "object") throw new Error("invalid planHint: expected an object");
+    const hr = h as Record<string, unknown>;
+    const nextHint = { ...next.planHint };
+    if ("on" in hr) {
+      if (typeof hr.on !== "boolean") throw new Error("invalid planHint.on: expected true/false");
+      nextHint.on = hr.on;
+    }
+    if ("everyTurn" in hr) {
+      if (typeof hr.everyTurn !== "boolean") throw new Error("invalid planHint.everyTurn: expected true/false");
+      nextHint.everyTurn = hr.everyTurn;
+    }
+    next.planHint = nextHint;
+  }
   cache = { ...cache, prefs: next, updatedAt: Date.now() };
   persist();
   return cache;
@@ -547,6 +587,12 @@ export function agentSettings(): AgentSettings {
   return cache.agent;
 }
 
+/** The plan-hint knobs. Read on EVERY prompt (not cached here), so the switch in 设置 takes effect
+ *  on the operator's very next turn — no restart, no session to hibernate. */
+export function planHintSettings(): PlanHintSettings {
+  return cache.prefs.planHint;
+}
+
 /** Normalise the two URL shapes operators paste: MaaS root or .../compatible-mode/v1. */
 export function dashscopeUrls(baseUrl: string): { root: string; compat: string; ws: string } {
   const trimmed = baseUrl.replace(/\/+$/, "");

package/packages/shared/src/index.ts

@@ -194,8 +194,48 @@ export type ServerEvent =
   | { t: "plan"; sessionId: string; plan: PlanSnapshot }
   /** context-window usage for a slot (ACP usage_update) */
   | { t: "usage"; sessionId: string; usage: UsageView }
+  /** A browser notification for this machine (the web channel of the notify feature).
+   *
+   *  Same decision as the phone's cards, second renderer: the server maps an ACP event to a
+   *  title/body ONCE (notify/center.ts §ACP mapping) and hands the page a render-ready object, so the
+   *  page never re-derives what happened. Nothing here is Android's `ActivityObject` — no channels,
+   *  importances or actions; a browser ignores them, and sending fields a renderer cannot use is how a
+   *  second contract starts.
+   *
+   *  No cursor and no replay, unlike the phone's device socket: a tab that was closed has a
+   *  transcript to catch up in, and a wall of stale cards after a reload is worse than none. */
+  | { t: "notify"; notice: WebNotice }
   | { t: "error"; error: string };
 
+/**
+ * Server -> page, one browser notification (see the `notify` frame above).
+ *
+ * NOTE for whoever touches drawing: the page's ONLY jobs are (1) is this device allowed and willing
+ * (`Notification` exists, secure context, permission granted, the operator's local switch on), (2) is
+ * this tab in the background (`document.hidden` — the page's own answer to 「我正在看就不弹」, made
+ * where the fact lives), (3) draw it with `noticeId` as the notification `tag`. Everything about WHAT
+ * happened and WHEN to say it is decided server-side. */
+export interface WebNotice {
+  /** `upsert` = show (or replace) the card for `noticeId`; `dismiss` = take it away. */
+  op: "upsert" | "dismiss";
+  /** The page's slot AND its notification `tag`: one id = one card, a newer one replaces the old.
+   *  Chosen so a session's running/done cards replace themselves while each pending approval keeps
+   *  its own (every one of those is a decision still waiting for an answer). */
+  noticeId: string;
+  /** Semantic kind, for the page's own choices (per-kind sound, and whether a click is expected). */
+  kind: "agent_running" | "approval" | "agent_done" | "error";
+  /** What happened (short — the line the OS draws first). */
+  title: string;
+  /** `<会话名> · <detail>`, the same shape the phone's cards use. */
+  body: string;
+  /** Where a click lands, relative to this server (`/?session=<id>`). The phone's tap target is the
+   *  same URL, so "open the session that notified me" has one owner. */
+  open?: string | null;
+  /** True when the card must WAIT for the operator (an approval) rather than fade on its own. */
+  sticky?: boolean;
+  at: number;
+}
+
 export interface TurnTrace {
   model?: string;
   provider?: string;