paseo-smart-session 1.2.6 → 2.1.0

package/client/guard/paused.tsx

@@ -0,0 +1,77 @@
+import { useEffect, useRef, useState } from "react";
+import { ActivityIndicator, Text, View } from "react-native";
+import { type PluginSurfaceProps, useRpc } from "@getpaseo/plugin/client";
+import { ScrollView } from "@getpaseo/plugin/client/react-native";
+import { SettingsAction, SettingsCard, SettingsInput, SettingsRow, SettingsSection } from "@getpaseo/plugin/client/ui";
+import { cancelResumeRpc, statusRpc } from "../../shared/guard/contracts.ts";
+import { governorNotice, pauseOwnerNote, pausedSessions, pausePresentation } from "../../shared/guard/presentation.ts";
+
+export function PausedSessions({ theme, host, layout, navigation, openSettings }: PluginSurfaceProps & { openSettings(): void }) {
+  const read = useRpc(statusRpc);
+  const cancel = useRpc(cancelResumeRpc);
+  const [status, setStatus] = useState<Awaited<ReturnType<typeof read>> | null>(null);
+  const [loadError, setLoadError] = useState<string | null>(null);
+  const [actionError, setActionError] = useState<string | null>(null);
+  const [busy, setBusy] = useState<string | null>(null);
+  const [query, setQuery] = useState("");
+  const refresh = useRef<() => Promise<void>>(async () => {});
+  useEffect(() => {
+    let stopped = false, fetching = false;
+    const fetch = async () => {
+      if (fetching || stopped) return;
+      fetching = true;
+      try { const next = await read({}); if (!stopped) { setStatus(next); setLoadError(null); } }
+      catch { if (!stopped) setLoadError("Could not refresh paused sessions. Showing the last report; retrying automatically."); }
+      finally { fetching = false; }
+    };
+    refresh.current = fetch;
+    void fetch(); const timer = setInterval(() => void fetch(), 5000);
+    return () => { stopped = true; clearInterval(timer); };
+  }, [read]);
+  const release = async (agentId: string) => {
+    if (busy) return;
+    setBusy(agentId);
+    try { await cancel({ agentId }); await refresh.current(); setActionError(null); }
+    catch { setActionError("Could not change this pause. Refresh the list and try again."); }
+    finally { setBusy(null); }
+  };
+  const all = status ? pausedSessions(status.pauses) : [];
+  const visible = status ? pausedSessions(status.pauses, query) : [];
+  const attention = visible.filter(p => p.phase === "attention");
+  const waiting = visible.filter(p => p.phase !== "attention");
+  const muted = { color: theme.colors.foregroundMuted, fontSize: 13, lineHeight: 20 };
+  // Both plugins share one state file: when this one is not governing, the list is
+  // the other plugin's (or a leftover), and its controls would only fail.
+  const notice = status ? governorNotice(status) : null;
+  const owner = status ? pauseOwnerNote(status) : null;
+  const row = (pause: typeof all[number]) => {
+    const presentation = pausePresentation(pause, status!.policy);
+    const hint = `${pause.provider} · ${pause.agentId.slice(0, 8)} · ${presentation.coverage}\n${presentation.resetLabel}\n${owner ?? presentation.state}${pause.note ? `\n${pause.note}` : ""}`;
+    return <View key={pause.id}>
+      {navigation ? <SettingsAction label={presentation.title} hint={hint} actionLabel="Open session" onPress={() => navigation.openAgent({ agentId: pause.agentId, serverId: host.id })} />
+        : <SettingsRow label={presentation.title} hint={hint} />}
+      {owner === null && <SettingsAction label={busy === pause.agentId ? "Updating this pause…" : "Manual control"} hint={presentation.actionHint} actionLabel={presentation.actionLabel} disabled={busy !== null} onPress={() => void release(pause.agentId)} />}
+    </View>;
+  };
+  return <ScrollView contentContainerStyle={{ padding: layout.compact ? 16 : 24, paddingBottom: 40 }}>
+    <View style={{ width: "100%", maxWidth: 760, alignSelf: "center", gap: 24 }}>
+      <View style={{ gap: 8 }}>
+        <Text accessibilityRole="header" style={{ color: theme.colors.foreground, fontSize: 22, fontWeight: "600" }}>Paused sessions</Text>
+        <Text style={muted}>All Session Guard pauses on {host.label}. Native subagents are included with their parent session.</Text>
+      </View>
+      {!status && !loadError && <ActivityIndicator accessibilityLabel="Loading paused sessions" color={theme.colors.foregroundMuted} />}
+      {notice && <SettingsCard><SettingsAction label={notice.title} hint={notice.hint} actionLabel="Settings" onPress={openSettings} /></SettingsCard>}
+      {status && !notice && <SettingsCard><SettingsAction label={`${all.length} ${all.length === 1 ? "session" : "sessions"} in Session Guard${all.some(p => p.phase === "attention") ? " · attention needed" : ""}`} hint={status.checkedAt ? `Last checked ${new Date(status.checkedAt).toLocaleTimeString([], { hour: "numeric", minute: "2-digit" })} · refreshes automatically` : "Waiting for the first usage check"} actionLabel="Refresh" onPress={() => void refresh.current()} /></SettingsCard>}
+      {(all.length > 5 || query !== "") && <SettingsCard><SettingsInput label="Find a paused session" placeholder="Title or provider" initialValue="" onChangeText={setQuery} /></SettingsCard>}
+      {status && all.length === 0 && !notice && <SettingsCard><SettingsRow label="No sessions are paused" hint="When a protected session reaches its limit, it appears here and receives a timeline entry." /></SettingsCard>}
+      {status && all.length > 0 && visible.length === 0 && <SettingsCard><SettingsRow label="No matching paused sessions" hint="Try another title or provider." /></SettingsCard>}
+      {owner && visible.length > 0 && <SettingsSection title={`Not managed by Smart Session (${visible.length})`}><SettingsCard>{visible.map(row)}</SettingsCard></SettingsSection>}
+      {!owner && attention.length > 0 && <SettingsSection title={`Needs attention (${attention.length})`}><SettingsCard>{attention.map(row)}</SettingsCard></SettingsSection>}
+      {!owner && waiting.length > 0 && <SettingsSection title={`Waiting for reset (${waiting.length})`}><SettingsCard>{waiting.map(row)}</SettingsCard></SettingsSection>}
+      <SettingsCard><SettingsAction label="Protection and timing" hint="Configure the default, native subagents, and automatic resume." actionLabel="Settings" onPress={openSettings} /></SettingsCard>
+      {loadError && <Text accessibilityRole="alert" style={{ ...muted, color: theme.colors.statusDanger }}>{status ? loadError : "Could not load paused sessions. Retrying automatically."}</Text>}
+      {actionError && <Text accessibilityRole="alert" style={{ ...muted, color: theme.colors.statusDanger }}>{actionError}</Text>}
+      {status?.error && !notice && <Text accessibilityRole="alert" style={{ ...muted, color: theme.colors.statusDanger }}>{status.error}</Text>}
+    </View>
+  </ScrollView>;
+}

package/client/guard/pill-icons.tsx

@@ -0,0 +1,26 @@
+import type { PluginButtonIcon, PluginButtonIconProps } from "@getpaseo/plugin/client";
+import { Icon } from "@getpaseo/plugin/client/react-native";
+
+// Like Smart Compact, keep the host's pill chrome and color the icon slot.
+function GuardOnIcon({ theme, size }: PluginButtonIconProps) {
+  return <Icon name="ShieldCheck" size={size} color={theme.colors.statusSuccess} />;
+}
+
+function GuardOffIcon({ theme, size }: PluginButtonIconProps) {
+  return <Icon name="ShieldOff" size={size} color={theme.colors.foregroundMuted} />;
+}
+
+function GuardPausedIcon({ theme, size }: PluginButtonIconProps) {
+  return <Icon name="Pause" size={size} color={theme.colors.statusWarning} />;
+}
+
+function GuardAttentionIcon({ theme, size }: PluginButtonIconProps) {
+  return <Icon name="TriangleAlert" size={size} color={theme.colors.statusDanger} />;
+}
+
+export const guardPillIcons: Readonly<Record<string, PluginButtonIcon>> = {
+  ShieldCheck: GuardOnIcon,
+  ShieldOff: GuardOffIcon,
+  Pause: GuardPausedIcon,
+  TriangleAlert: GuardAttentionIcon,
+};

package/client/guard/pills.ts

@@ -0,0 +1,122 @@
+/**
+ * The Session Guard pill: one per live session, beside Smart Compact's.
+ *
+ * Drawn only while this plugin is the host's Session Guard governor. Off, there is
+ * nothing for it to say; deferring to the standalone plugin, that plugin draws its own,
+ * and two shields on one composer would contradict each other. While the feature is
+ * being turned off, a session that still has a pause keeps its pill so the pause can
+ * be released from where it is.
+ */
+import type { PluginButtonIcon, PluginClientContext } from "@getpaseo/plugin/client";
+import type { AgentDirectory } from "../agents.ts";
+import { GUARD_SURFACES } from "./surfaces.ts";
+import { cancelResumeRpc, setProtectionRpc, statusRpc } from "../../shared/guard/contracts.ts";
+import { isPending, protects, type Pause, type Policy } from "../../shared/guard/policy.ts";
+
+export function pillPresentation(policy: Policy, enabled: boolean, pause: Pause | undefined) {
+  if (!policy.enabled) return { label: "Guard off", title: "Session Guard is disabled on this host", icon: "ShieldOff" };
+  if (!enabled) return { label: "Guard off", title: "This session is excluded from automatic quota protection", icon: "ShieldOff" };
+  if (pause?.phase === "attention") return { label: "Check session", title: pause.note ?? "Check this session before continuing", icon: "TriangleAlert" };
+  if (pause) {
+    if (pause.demo) return { label: "Paused · demo", title: "This test session is paused. Try Resume now in its timeline; no provider quota was changed.", icon: "Pause" };
+    const date = pause.anchorResetsAt ? new Date(pause.anchorResetsAt) : null;
+    const time = date && Number.isFinite(date.getTime()) ? date.toLocaleTimeString([], { hour: "numeric", minute: "2-digit" }) : null;
+    const resetDetail = date ? ` Expected reset ${date.toLocaleString([], { dateStyle: "short", timeStyle: "short" })}.` : " Reset time is not available yet.";
+    return { label: time ? `Paused · ${time}` : "Paused · awaiting reset", title: (policy.autoResume
+      ? `Paused at the session limit${pause.suspension ? ", including native subagents" : ""}. Automatic continuation is scheduled after reset.`
+      : pause.suspension ? "Session and native subagents are paused. Release and turn off to continue manually; automatic continuation is off."
+      : "Paused at the session limit. Continue manually after reset; automatic continuation is off.") + resetDetail, icon: "Pause" };
+  }
+  return { label: "Session Guard", title: policy.autoResume
+    ? `Pause at ${policy.thresholdPct}% session usage and continue after reset`
+    : `Pause at ${policy.thresholdPct}% session usage; continue manually after reset`, icon: "ShieldCheck" };
+}
+
+/** How often a client re-reads Session Guard status while it is on, and while it is off. */
+const ACTIVE_POLL_MS = 5_000;
+const IDLE_POLL_MS = 60_000;
+
+const wakers = new Set<() => void>();
+/**
+ * Re-reads status now. The settings screens call it whenever the Session Guard
+ * document changes — their `useSettings` hears changes from every client — so pills
+ * follow a switch without polling hard while the feature is off.
+ */
+export function refreshGuardPills(): void {
+  for (const wake of [...wakers]) wake();
+}
+
+export function contributePills(client: PluginClientContext, agents: AgentDirectory, icons: Readonly<Record<string, PluginButtonIcon>> = {}) {
+  let stopped = false;
+  let running = false;
+  let status: Awaited<ReturnType<typeof readStatus>> | null = null;
+  const handles = new Map<string, { workspaceId: string; signature: string; registration: ReturnType<PluginClientContext["addComposerPill"]> }>();
+  const readStatus = () => client.rpc(statusRpc, {});
+  let timer: ReturnType<typeof setTimeout> | null = null;
+  const refresh = async () => {
+    if (stopped || running) return;
+    running = true;
+    if (timer !== null) clearTimeout(timer);
+    timer = null;
+    try { const next = await readStatus(); if (!stopped) { status = next; reconcile(); } }
+    catch { /* Keep the last confirmed presentation across a brief disconnect. */ }
+    finally {
+      running = false;
+      // Off here and nobody governing from here: nothing to draw, so check rarely.
+      const idle = status !== null && !status.policy.enabled && status.governor === "off";
+      if (!stopped) timer = setTimeout(() => void refresh(), idle ? IDLE_POLL_MS : ACTIVE_POLL_MS);
+    }
+  };
+  function reconcile() {
+    if (stopped || !status) return;
+    const sessions = new Map<string, string>();
+    if (status.governor === "active") {
+      for (const [agentId, agent] of agents.current()) {
+        if (agent.closed) continue;
+        if (status.policy.enabled || status.pauses.some(p => p.agentId === agentId && isPending(p))) sessions.set(agentId, agent.workspaceId);
+      }
+    }
+    for (const [id, handle] of handles) {
+      if (sessions.get(id) !== handle.workspaceId) { handle.registration.remove(); handles.delete(id); }
+    }
+    for (const [agentId, workspaceId] of sessions) {
+      const enabled = protects(status.policy, status.overrides, agentId);
+      const pause = status.pauses.find(p => p.agentId === agentId && isPending(p));
+      const presentation = pillPresentation(status.policy, enabled, pause);
+      const signature = JSON.stringify([presentation, enabled, agentId in status.overrides, pause?.id]);
+      const handle = handles.get(agentId);
+      // Preserve the host menu while polling or receiving agent updates.
+      // Replacing behavior on every read remounts an open adaptive menu.
+      if (handle?.signature === signature) continue;
+      const button = {
+        ...presentation,
+        icon: icons[presentation.icon] ?? presentation.icon,
+        behavior: { kind: "menu" as const, items: [
+          { kind: "item" as const, id: "toggle", title: enabled ? "Turn off for this session" : "Protect this session", icon: enabled ? "ShieldOff" : "ShieldCheck",
+            behavior: { kind: "action" as const, onPress: async () => { await client.rpc(setProtectionRpc, { agentId, enabled: !enabled }); await refresh(); } } },
+          { kind: "item" as const, id: "default", title: "Use host default", visible: agentId in status.overrides,
+            behavior: { kind: "action" as const, onPress: async () => { await client.rpc(setProtectionRpc, { agentId, enabled: null }); await refresh(); } } },
+          { kind: "item" as const, id: "cancel", title: pause?.suspension ? "Release and turn off for this session" : "Cancel automatic continuation", visible: !!pause,
+            behavior: { kind: "action" as const, onPress: async () => { await client.rpc(cancelResumeRpc, { agentId }); await refresh(); } } },
+          { kind: "separator" as const, id: "separator" },
+          { kind: "item" as const, id: "paused-sessions", title: "All paused sessions", icon: "Pause",
+            behavior: { kind: "action" as const, onPress: () => { client.openSurface(GUARD_SURFACES.paused); } } },
+          { kind: "item" as const, id: "settings", title: "Session Guard settings", icon: "Settings",
+            behavior: { kind: "action" as const, onPress: () => { client.openSurface(GUARD_SURFACES.settings); } } },
+        ] },
+      };
+      if (handle) { handle.registration.update(button); handle.signature = signature; }
+      else handles.set(agentId, { workspaceId, signature, registration: client.addComposerPill({ id: "session-guard", workspaceId, agentId, button }) });
+    }
+  }
+  const unsubscribe = agents.subscribe(reconcile);
+  const wake = () => void refresh();
+  wakers.add(wake);
+  void refresh();
+  return () => {
+    stopped = true; wakers.delete(wake); unsubscribe();
+    if (timer !== null) clearTimeout(timer);
+    for (const handle of handles.values()) handle.registration.remove();
+    handles.clear();
+  };
+}

package/client/guard/settings.tsx

@@ -0,0 +1,114 @@
+import { useEffect, useState } from "react";
+import { ActivityIndicator, Text, View } from "react-native";
+import { useRpc, useSettings, type PluginSurfaceProps } from "@getpaseo/plugin/client";
+import { SettingsAction, SettingsCard, SettingsInput, SettingsRow, SettingsSection, SettingsSelect, SettingsSwitch } from "@getpaseo/plugin/client/ui";
+import { cancelResumeRpc, guardPreferences, setProtectionRpc, statusRpc } from "../../shared/guard/contracts.ts";
+import { isPending, PolicySchema, type Policy } from "../../shared/guard/policy.ts";
+import { governorNotice, pauseOwnerNote } from "../../shared/guard/presentation.ts";
+import { refreshGuardPills } from "./pills.ts";
+
+type Draft = { thresholdPct: string; pollSeconds: string; resetGraceSeconds: string; resumeSpacingSeconds: string; continuation: string; providerIds: string; windowIds: string };
+function draftOf(policy: Policy): Draft {
+  return { thresholdPct: String(policy.thresholdPct), pollSeconds: String(policy.pollSeconds), resetGraceSeconds: String(policy.resetGraceSeconds),
+    resumeSpacingSeconds: String(policy.resumeSpacingSeconds), continuation: policy.continuation, providerIds: policy.providerIds.join(", "), windowIds: policy.windowIds.join(", ") };
+}
+const list = (value: string) => [...new Set(value.split(",").map(s => s.trim()).filter(Boolean))];
+
+export function GuardSettings({ theme, openOverview }: PluginSurfaceProps & { openOverview(): void }) {
+  const settings = useSettings(guardPreferences);
+  const values = settings.status === "ready" ? settings.values : undefined;
+  // Pills poll slowly while the feature is off; tell them as soon as it changes.
+  useEffect(() => {
+    if (values !== undefined) refreshGuardPills();
+  }, [values]);
+  const readStatus = useRpc(statusRpc);
+  const cancelResume = useRpc(cancelResumeRpc);
+  const setProtection = useRpc(setProtectionRpc);
+  const [status, setStatus] = useState<Awaited<ReturnType<typeof readStatus>> | null>(null);
+  const [error, setError] = useState<string | null>(null);
+  const [statusError, setStatusError] = useState<string | null>(null);
+  const [draft, setDraft] = useState<Draft | null>(null);
+  const [revision, setRevision] = useState<string | null>(null);
+  useEffect(() => {
+    let stopped = false;
+    let pending = false;
+    const refresh = async () => {
+      if (pending || stopped) return;
+      pending = true;
+      try { const next = await readStatus({}); if (!stopped) { setStatus(next); setStatusError(null); } }
+      catch { if (!stopped) setStatusError("Could not load current session status. Retrying automatically."); }
+      finally { pending = false; }
+    };
+    void refresh(); const timer = setInterval(() => void refresh(), 5000);
+    return () => { stopped = true; clearInterval(timer); };
+  }, [readStatus]);
+  if (settings.status === "loading") return <ActivityIndicator accessibilityLabel="Loading Session Guard settings" color={theme.colors.foregroundMuted} />;
+  if (settings.status !== "ready") return <View style={{ gap: 12 }}>
+    <Text accessibilityRole="alert" style={{ color: theme.colors.statusDanger }}>{settings.error}</Text>
+    <SettingsCard><SettingsAction label="Load saved settings again" actionLabel="Retry" onPress={() => void settings.reload()} />
+      {settings.status === "invalid" && <SettingsAction label="Replace invalid settings with defaults" actionLabel="Reset" onPress={() => void settings.reset()} disabled={settings.saving} />}</SettingsCard>
+  </View>;
+  const change = (patch: Partial<Policy>) => void settings.save({ ...settings.values, ...patch }, settings.revision);
+  const action = async (work: () => Promise<unknown>) => {
+    try { await work(); setStatus(await readStatus({})); setError(null); }
+    catch { setError("The change could not be saved. Try again."); }
+  };
+  const saveAdvanced = async () => {
+    if (!draft || !revision) return;
+    const parsed = PolicySchema.safeParse({ ...settings.values, ...draft,
+      thresholdPct: Number(draft.thresholdPct), pollSeconds: Number(draft.pollSeconds), resetGraceSeconds: Number(draft.resetGraceSeconds), resumeSpacingSeconds: Number(draft.resumeSpacingSeconds),
+      providerIds: list(draft.providerIds), windowIds: list(draft.windowIds),
+    });
+    if (!parsed.success) { setError(parsed.error.issues.map(i => `${i.path.join(".")}: ${i.message}`).join("\n")); return; }
+    if (await settings.save(parsed.data, revision)) { setDraft(null); setRevision(null); setError(null); }
+  };
+  const text = { color: theme.colors.foregroundMuted, fontSize: 13, lineHeight: 20 };
+  const waiting = status?.pauses.filter(isPending) ?? [];
+  // A non-governing plugin can show the shared pauses but cannot act on them.
+  const notice = status ? governorNotice(status) : null;
+  const owner = status ? pauseOwnerNote(status) : null;
+  return <View style={{ gap: 24 }}>
+    <Text style={text}>Pause work at the provider’s session limit, then continue the same conversation after reset. Your workspace and conversation stay in place.</Text>
+    {notice && status?.governor !== "off" && <SettingsCard><SettingsRow label={notice.title} hint={notice.hint} /></SettingsCard>}
+    <SettingsSection title="Protection"><SettingsCard>
+      <SettingsSwitch label="Enable Session Guard" hint="Off until you turn it on. Runs even when Paseo’s app is closed. Turning it off releases suspended workers; message continuations wait until you turn it back on or cancel them." value={settings.values.enabled} disabled={settings.saving || !!draft} onValueChange={enabled => change({ enabled })} />
+      <SettingsSelect label="Default for sessions" hint="Each session’s composer pill can override this default. Existing explicit overrides stay in place." value={settings.values.protectByDefault ? "all" : "opt-in"} options={[{ label: "Protect all sessions", value: "all" }, { label: "Opt in per session", value: "opt-in" }]} disabled={settings.saving || !!draft} onValueChange={value => change({ protectByDefault: value === "all" })} />
+      <SettingsSwitch label="Continue automatically after reset" hint="Waits for a fresh usage report below your threshold. Turn this off to continue manually." value={settings.values.autoResume} disabled={settings.saving || !!draft} onValueChange={autoResume => change({ autoResume })} />
+      <SettingsSwitch label="Include native subagents" hint="On Linux, pause Claude and Codex sessions together with their nested workers. Turn this off to interrupt only the foreground turn." value={settings.values.includeNativeSubagents} disabled={settings.saving || !!draft} onValueChange={includeNativeSubagents => change({ includeNativeSubagents })} />
+      <SettingsSwitch label="Label paused workspaces" hint="Show an amber Paused label in the left sidebar until every paused session in that workspace is released." value={settings.values.workspaceLabels} disabled={settings.saving || !!draft} onValueChange={workspaceLabels => change({ workspaceLabels })} />
+    </SettingsCard></SettingsSection>
+    <SettingsSection title="Waiting for reset"><SettingsCard>
+      {!status && <SettingsRow label="Loading session status…" />}
+      {status && waiting.length === 0 && <SettingsRow label="No sessions are paused" hint="Protected work will appear here when the session limit is reached." />}
+      {waiting.map(pause => {
+        const hint = pause.note ?? `${pause.provider}${pause.suspension ? " · Includes native subagents" : ""} · ${pause.anchorResetsAt ? `Reset ${new Date(pause.anchorResetsAt).toLocaleString([], { dateStyle: "short", timeStyle: "short" })}` : "Waiting for usage to become available"}`;
+        return owner ? <SettingsRow key={pause.id} label={pause.title ?? "Untitled session"} hint={`${hint}\n${owner}`} />
+          : <SettingsAction key={pause.id} label={pause.title ?? "Untitled session"} hint={hint} actionLabel={pause.suspension ? "Release and turn off" : "Cancel continuation"} disabled={settings.saving} onPress={() => void action(() => cancelResume({ agentId: pause.agentId }))} />;
+      })}
+      <SettingsAction label="All paused sessions" hint="Open sessions, check reset times, and manage each pause in one place." actionLabel="Open list" onPress={openOverview} />
+    </SettingsCard></SettingsSection>
+    {status && Object.keys(status.overrides).length > 0 && <SettingsSection title="Session overrides"><SettingsCard>
+      {Object.entries(status.overrides).map(([agentId, enabled]) => {
+        const label = status.pauses.find(p => p.agentId === agentId)?.title ?? `Session ${agentId.slice(0, 8)}`;
+        const hint = enabled ? "Explicitly protected" : "Excluded from protection";
+        return status.governor === "active" ? <SettingsAction key={agentId} label={label} hint={hint} actionLabel="Use default" onPress={() => void action(() => setProtection({ agentId, enabled: null }))} />
+          : <SettingsRow key={agentId} label={label} hint={hint} />;
+      })}
+    </SettingsCard></SettingsSection>}
+    <SettingsSection title="Timing and continuation"><SettingsCard>
+      {!draft ? <SettingsAction label={`Pause at ${settings.values.thresholdPct}% session usage`} hint={`Check every ${settings.values.pollSeconds}s · wait ${settings.values.resetGraceSeconds}s after reset · space continuations by ${settings.values.resumeSpacingSeconds}s`} actionLabel="Edit" onPress={() => { setDraft(draftOf(settings.values)); setRevision(settings.revision); }} /> : <>
+        <SettingsInput label="Pause threshold (%)" hint="1–100. Default: 100." initialValue={draft.thresholdPct} disabled={settings.saving} onChangeText={value => setDraft(previous => previous && { ...previous, thresholdPct: value })} />
+        <SettingsInput label="Check interval (seconds)" hint="5–300. Upstream usage may be cached by Paseo; this cannot force a provider refresh." initialValue={draft.pollSeconds} disabled={settings.saving} onChangeText={value => setDraft(previous => previous && { ...previous, pollSeconds: value })} />
+        <SettingsInput label="Wait after reset (seconds)" hint="0–600. Default: 30." initialValue={draft.resetGraceSeconds} disabled={settings.saving} onChangeText={value => setDraft(previous => previous && { ...previous, resetGraceSeconds: value })} />
+        <SettingsInput label="Space continuations (seconds)" hint="0–300. Avoid sending every paused session at once." initialValue={draft.resumeSpacingSeconds} disabled={settings.saving} onChangeText={value => setDraft(previous => previous && { ...previous, resumeSpacingSeconds: value })} />
+        <SettingsInput label="Continuation message" hint="Sent once into the same conversation after the reset is confirmed." initialValue={draft.continuation} disabled={settings.saving} onChangeText={value => setDraft(previous => previous && { ...previous, continuation: value })} />
+        <SettingsInput label="Provider IDs" hint="Comma separated. Leave empty to protect all providers reporting session usage." initialValue={draft.providerIds} disabled={settings.saving} onChangeText={value => setDraft(previous => previous && { ...previous, providerIds: value })} />
+        <SettingsInput label="Session window IDs" hint="Comma separated, in preference order. Default: five_hour, session." initialValue={draft.windowIds} disabled={settings.saving} onChangeText={value => setDraft(previous => previous && { ...previous, windowIds: value })} />
+        <SettingsAction label="Apply timing and continuation" actionLabel="Save changes" disabled={settings.saving} onPress={() => void saveAdvanced()} />
+        <SettingsAction label="Keep saved values" actionLabel="Discard changes" disabled={settings.saving} onPress={() => { setDraft(null); setRevision(null); setError(null); }} />
+      </>}
+    </SettingsCard></SettingsSection>
+    {(error || settings.saveError) && <Text accessibilityRole="alert" style={{ color: theme.colors.statusDanger }}>{error ?? settings.saveError}</Text>}
+    {(statusError || status?.error) && <Text accessibilityRole="alert" style={{ color: theme.colors.statusDanger }}>{statusError ?? status?.error}</Text>}
+  </View>;
+}

package/client/guard/surfaces.ts

@@ -0,0 +1,2 @@
+/** Session Guard's surfaces, opened from its pill, the overview, settings and timeline. */
+export const GUARD_SURFACES = { paused: "paused-sessions", settings: "session-guard" } as const;

package/client/guard/timeline.tsx

@@ -0,0 +1,94 @@
+import { useEffect, useState } from "react";
+import { Pressable, Text, View } from "react-native";
+import { useRpc, type PluginTimelineItemProps } from "@getpaseo/plugin/client";
+import { Icon } from "@getpaseo/plugin/client/react-native";
+import { timelinePresentation, type TimelineData } from "../../shared/guard/timeline.ts";
+import { dismissPauseRpc, resumeNowRpc, statusRpc } from "../../shared/guard/contracts.ts";
+import type { Pause } from "../../shared/guard/policy.ts";
+
+export function GuardTimelineItem({ theme, agentId, item, openOverview }: PluginTimelineItemProps<TimelineData> & { openOverview(): void }) {
+  const readStatus = useRpc(statusRpc);
+  const resumeNow = useRpc(resumeNowRpc);
+  const dismissPause = useRpc(dismissPauseRpc);
+  const [pause, setPause] = useState<Pause | null>(null);
+  const [loaded, setLoaded] = useState(false);
+  const [action, setAction] = useState<"resume" | "dismiss" | null>(null);
+  const busy = action !== null;
+  const [error, setError] = useState<string | null>(null);
+  const [statusError, setStatusError] = useState<string | null>(null);
+  useEffect(() => {
+    if (!["paused", "recovery"].includes(item.data.event)) return;
+    setPause(null); setLoaded(false); setError(null); setStatusError(null);
+    let stopped = false, pending = false;
+    const refresh = async () => {
+      if (pending || stopped) return;
+      pending = true;
+      try {
+        const status = await readStatus({});
+        if (!stopped) { setPause(status.pauses.find(p => p.id === item.data.pauseId && p.agentId === agentId) ?? null); setLoaded(true); setStatusError(null); }
+      } catch { if (!stopped) setStatusError("Could not check this pause. Retrying automatically."); }
+      finally { pending = false; }
+    };
+    void refresh(); const timer = setInterval(() => void refresh(), 5000);
+    return () => { stopped = true; clearInterval(timer); };
+  }, [readStatus, agentId, item.data.event, item.data.pauseId]);
+  const act = async (kind: "resume" | "dismiss") => {
+    if (busy) return;
+    setAction(kind); setError(null);
+    try {
+      await (kind === "resume" ? resumeNow : dismissPause)({ agentId, pauseId: item.data.pauseId });
+      const status = await readStatus({});
+      setPause(status.pauses.find(p => p.id === item.data.pauseId && p.agentId === agentId) ?? null);
+    } catch { setError(kind === "resume" ? "Resume could not be confirmed. Check the session before trying again."
+      : "Dismissal could not be confirmed. Check the pause status; you can retry dismissal without sending a message."); }
+    finally { setAction(null); }
+  };
+  if (pause?.phase === "cancelled" && pause.dismissed && ["paused", "recovery"].includes(item.data.event)) return <View style={{ flexDirection: "row", alignItems: "flex-start", gap: 8, padding: 14 }}>
+    <Icon name="ShieldOff" size={16} color={theme.colors.foregroundMuted} />
+    <Text style={{ color: theme.colors.foregroundMuted, fontSize: 12, lineHeight: 18 }}>Pause dismissed · no message sent · protection off</Text>
+  </View>;
+  const presentation = timelinePresentation(item.data);
+  const color = presentation.tone === "warning" ? theme.colors.statusWarning : presentation.tone === "success" ? theme.colors.statusSuccess
+    : presentation.tone === "danger" ? theme.colors.statusDanger : theme.colors.foregroundMuted;
+  return <View style={{ borderWidth: 1, borderColor: theme.colors.border, borderRadius: 8, backgroundColor: theme.colors.surface1, padding: 14, gap: 10 }}>
+    <View style={{ flexDirection: "row", alignItems: "center", gap: 8 }}>
+      <Icon name={presentation.icon} size={18} color={color} />
+      <Text style={{ color: theme.colors.foreground, fontSize: 14, fontWeight: "600", flex: 1 }}>{presentation.title}</Text>
+    </View>
+    <Text style={{ color: theme.colors.foregroundMuted, fontSize: 13, lineHeight: 20 }}>{presentation.detail}</Text>
+    <Text style={{ color: theme.colors.foregroundMuted, fontSize: 12 }}>{new Date(item.data.at).toLocaleString([], { dateStyle: "short", timeStyle: "short" })}</Text>
+    {["paused", "recovery"].includes(item.data.event) && <View style={{ gap: 6 }}>
+      {!loaded && <Text style={{ color: theme.colors.foregroundMuted, fontSize: 12 }}>Checking pause status…</Text>}
+      {pause?.phase === "waiting" && <>
+        <View style={{ flexDirection: "row", flexWrap: "wrap", gap: 8 }}>
+        <Pressable accessibilityRole="button" accessibilityLabel="Resume now" accessibilityState={{ disabled: busy, busy: action === "resume" }} disabled={busy} onPress={() => void act("resume")} style={({ pressed }) => ({ alignSelf: "flex-start", minHeight: 44, flexDirection: "row", alignItems: "center", gap: 8, paddingHorizontal: 12, borderWidth: 1, borderColor: theme.colors.border, borderRadius: 8, opacity: busy || pressed ? 0.6 : 1 })}>
+          <Icon name="Play" size={16} color={theme.colors.statusSuccess} />
+          <Text style={{ color: theme.colors.foreground, fontSize: 13, fontWeight: "600" }}>{action === "resume" ? "Resuming…" : "Resume now"}</Text>
+        </Pressable>
+        <Pressable accessibilityRole="button" accessibilityLabel="Dismiss pause without sending a message" accessibilityState={{ disabled: busy, busy: action === "dismiss" }} disabled={busy} onPress={() => void act("dismiss")} style={({ pressed }) => ({ alignSelf: "flex-start", minHeight: 44, flexDirection: "row", alignItems: "center", gap: 8, paddingHorizontal: 12, borderWidth: 1, borderColor: theme.colors.border, borderRadius: 8, opacity: busy || pressed ? 0.6 : 1 })}>
+          <Icon name="ShieldOff" size={16} color={theme.colors.foregroundMuted} />
+          <Text style={{ color: theme.colors.foreground, fontSize: 13 }}>{action === "dismiss" ? "Dismissing…" : "Dismiss pause"}</Text>
+        </Pressable>
+        </View>
+        <Text style={{ color: theme.colors.foregroundMuted, fontSize: 12, lineHeight: 18 }}>{item.data.demo
+          ? "Releases this test session and turns its protection off."
+          : "Turns protection off for this session. The provider may still reject work until reset."}</Text>
+        <Text style={{ color: theme.colors.foregroundMuted, fontSize: 12, lineHeight: 18 }}>Dismiss cancels automatic continuation without sending a message. Existing workers are released and may continue their current work.</Text>
+      </>}
+      {loaded && pause?.phase === "resumed" && <Text style={{ color: theme.colors.foregroundMuted, fontSize: 12 }}>{pause.manualResume ? "Resumed · protection off for this session" : "This pause has already resumed."}</Text>}
+      {loaded && (!pause || pause.phase === "cancelled") && <Text style={{ color: theme.colors.foregroundMuted, fontSize: 12 }}>This pause is no longer active.</Text>}
+      {pause?.phase === "resuming" && <Text style={{ color: theme.colors.foregroundMuted, fontSize: 12 }}>Resuming session…</Text>}
+      {pause?.phase === "attention" && <>
+        <Text style={{ color: theme.colors.statusDanger, fontSize: 12 }}>{pause.dismissed ? "Worker release needs attention. Automatic continuation is cancelled." : "Check the session before continuing manually."}</Text>
+        {pause.dismissed && <Pressable accessibilityRole="button" accessibilityLabel="Retry dismissing pause without sending a message" disabled={busy} accessibilityState={{ disabled: busy, busy: action === "dismiss" }} onPress={() => void act("dismiss")} style={{ minHeight: 44, justifyContent: "center" }}>
+          <Text style={{ color: theme.colors.foreground, fontSize: 13, textDecorationLine: "underline" }}>{action === "dismiss" ? "Dismissing…" : "Retry dismissal"}</Text>
+        </Pressable>}
+      </>}
+      {error && <Text accessibilityRole="alert" style={{ color: theme.colors.statusDanger, fontSize: 12 }}>{error}</Text>}
+      {statusError && <Text accessibilityRole="alert" style={{ color: theme.colors.statusDanger, fontSize: 12 }}>{statusError}</Text>}
+    </View>}
+    <Pressable accessibilityRole="button" accessibilityLabel="See all paused sessions" onPress={openOverview} style={({ pressed }) => ({ alignSelf: "flex-start", minHeight: 44, justifyContent: "center", paddingVertical: 8, paddingHorizontal: 2, opacity: pressed ? 0.7 : 1 })}>
+      <Text style={{ color: theme.colors.foreground, fontSize: 13, textDecorationLine: "underline" }}>See all paused sessions</Text>
+    </Pressable>
+  </View>;
+}

package/client/navigation.tsx

@@ -0,0 +1,14 @@
+import type { ComponentType } from "react";
+import type { PluginClientContext, PluginSurfaceProps } from "@getpaseo/plugin/client";
+import { Pressable, Text, View } from "react-native";
+
+export function withNavigation<P extends PluginSurfaceProps>(Component: ComponentType<P>, client: PluginClientContext, home: string, active = "overview") {
+  return function PluginView(props: P) {
+    return <View style={{ flex: 1, backgroundColor: props.theme.colors.surface0 }}>
+      <View accessibilityRole="toolbar" style={{ flexDirection: "row", flexWrap: "wrap", gap: 4, padding: 8, borderBottomWidth: 1, borderColor: props.theme.colors.border }}>
+        {[{ id: "overview", title: "Overview", target: home }, { id: "session-guard", title: "Session Guard", target: "session-guard" }, { id: "display", title: "Display settings", target: "display-settings" }].map(item => <Pressable key={item.id} accessibilityRole="button" accessibilityState={{ selected: active === item.id }} onPress={() => client.openSurface(item.target)} style={({ pressed }) => ({ minHeight: 44, paddingHorizontal: 12, justifyContent: "center", borderRadius: 6, backgroundColor: pressed || active === item.id ? props.theme.colors.surface2 : "transparent" })}><Text style={{ color: active === item.id ? props.theme.colors.foreground : props.theme.colors.foregroundMuted, fontSize: 13, fontWeight: active === item.id ? "600" : "400" }}>{item.title}</Text></Pressable>)}
+      </View>
+      <Component {...props} />
+    </View>;
+  };
+}