paseo-smart-session 3.2.0 → 3.3.0

package/docs/session-guard.md

@@ -81,6 +81,8 @@ If a reload or connection loss interrupts an unconfirmed stop/send, the pill rea
 - **ZeroSub goes first.** The guard doesn't pause an agent while ZeroSub's automatic switching is on and another account of the same provider has room. Room means signed in, not disabled, no recorded limit, and a reading under 30 minutes old that is below the threshold.
   - A session the guard already froze is released when such an account appears, so the CLI reaches the limit and ZeroSub can switch it.
   - Once no account has room, the guard pauses and continues as before.
+- **Every account out pauses, whichever side sees it first.** An account is out when it's at or over the threshold, at a limit ZeroSub recorded, or has any full window, including the weekly one. When the guard's reading gets there first, it pauses ahead of the CLI as usual. When the CLI gets there first, Claude ends the turn with its "You've hit your … limit" reply rather than an error. The guard reads that reply the way ZeroSub does and records a waiting pause once ZeroSub has recorded the limit. A pause racing that reply is kept, not released and taken again.
+- **Any account getting room continues it, once.** If the agent's own account resets, it continues there. If another account gets room first (confirmed by a ZeroSub reading taken after the pause), the guard sends its continuation anyway. That turn meets the limit on the old account, and ZeroSub moves the agent to the account with room and continues it with its own prompt. With automatic continuation off (`autoResume`), the pause waits for you as before.
 - **A moved session continues sooner.** An interrupted session that ZeroSub moves to an account with room is continued as soon as that account's reading confirms the room. It doesn't wait for the old account's reset.
 - **Codex tasks aren't continued twice.** When ZeroSub carries a Codex task on in another tab, the old tab's waiting continuation is cancelled.
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "paseo-smart-session",
   "type": "module",
-  "version": "3.2.0",
+  "version": "3.3.0",
   "license": "MIT",
   "description": "Records Claude plan-usage history and lets a Paseo agent manage its own context.",
   "repository": {

package/server/guard/engine.ts

@@ -166,6 +166,15 @@ export class Engine {
       this.quotaFailures.set(agentId, { at: new Date(this.now()).toISOString(), turnId });
     }
   }
+  /**
+   * The agent's finished turn ended on the CLI's limit notice (`shared/guard/limit-notice.ts`).
+   * Claude completes such a turn rather than failing it, so this is how a pause is recorded
+   * when the CLI reaches the limit before the guard's reading does. Only reported while
+   * ZeroSub is enabled, whose own detection this mirrors.
+   */
+  limitReached(agentId: string, turnId: string | null) {
+    this.quotaFailures.set(agentId, { at: new Date(this.now()).toISOString(), turnId });
+  }
   private async leftDaemon(suspension: NonNullable<Pause["suspension"]>) {
     return !!this.processes && ((this.processes.alive && !await this.processes.alive(suspension)) ||
       (this.processes.owned && !await this.processes.owned(suspension))) === true;
@@ -327,7 +336,7 @@ export class Engine {
     pause.phase = "cancelled"; pause.note = note; pause.settledAt = new Date(this.now()).toISOString();
   }
   /** A normally completed turn racing cancel must never become a continuation. */
-  async turnEnded(agentId: string, turnId: string | null, outcome: string) {
+  async turnEnded(agentId: string, turnId: string | null, outcome: string, endedOnLimit = false) {
     return this.exclusive(async () => {
       if (!["completed", "canceled"].includes(outcome)) return;
       const state = await this.store.read();
@@ -342,6 +351,12 @@ export class Engine {
         }
         if (outcome !== "completed") continue;
         if (turnId !== null && pause.turnId === turnId) {
+          if (endedOnLimit) {
+            // It completed on the limit notice, not with the work done: the same pause
+            // stands, now as the quota stop it is, rather than a release and a second pause.
+            if (!pause.wasQuotaFailure) { pause.wasQuotaFailure = true; changed = true; }
+            continue;
+          }
           await this.cancel(pause, "The interrupted turn completed before the pause."); changed = true;
         }
       }
@@ -397,6 +412,10 @@ export class Engine {
       this.accounts = accounts;
       const usageOf = (agentId: string, provider: string) => accounts?.usageFor(agentId, provider) ?? usage;
       const failsOver = (agentId: string, provider: string) => accounts?.failsOver(agentId, provider) ?? false;
+      // A pause can continue once its own account resets, or — with ZeroSub — once any
+      // account it can use has room, shown by a reading newer than the pause.
+      const ready = (pause: Pause) => resetReady(pause, usageOf(pause.agentId, pause.provider), policy, this.now()) ||
+        (!!accounts && accounts.roomSince(pause.agentId, pause.provider, timestamp(pause.pausedAt)!) !== null);
       const byId = new Map(agents.map(a => [a.id, a]));
       this.providers = new Map(agents.map(a => [a.id, a.provider]));
       const currentDaemon = await this.processes?.daemonIdentity?.();
@@ -465,7 +484,7 @@ export class Engine {
           if ((agent.activeTurn?.turnId ?? null) !== pause.turnId && !await nativeRunning(agent.id)) {
             await this.cancel(pause, "The suspended turn was stopped or changed outside Session Guard."); changed = true; continue;
           }
-          if (pause.demo || !policy.autoResume || this.now() < this.nextResumeAt || !resetReady(pause, usageOf(pause.agentId, pause.provider), policy, this.now())) continue;
+          if (pause.demo || !policy.autoResume || this.now() < this.nextResumeAt || !ready(pause)) continue;
           const latest = (await client.fetchAgent(pause.agentId))?.agent;
           if (!latest || latest.archivedAt || latest.status === "closed" || latest.provider !== pause.provider ||
             (latest.lastUserMessageAt ?? null) !== pause.lastUserMessageAt ||
@@ -488,8 +507,10 @@ export class Engine {
           await this.cancel(pause, "Work was continued outside Session Guard."); changed = true; continue;
         }
         const canContinue = (candidate: Agent) => candidate.status === "idle" || (pause.closedOnRestart && candidate.status === "closed") || (pause.wasQuotaFailure && candidate.status === "error");
+        // With ZeroSub, room on another account also continues it: the continuation meets the
+        // limit on this account, and ZeroSub fails it over there and carries it on.
         if (!canContinue(agent) || agent.pendingPermissions?.length || !policy.autoResume ||
-          this.now() < this.nextResumeAt || !resetReady(pause, usageOf(pause.agentId, pause.provider), policy, this.now())) continue;
+          this.now() < this.nextResumeAt || !ready(pause)) continue;
         // Re-read just before sending: a person may have continued while usage was fetched.
         const latest = (await client.fetchAgent(pause.agentId))?.agent;
         if (!latest || !canContinue(latest) || latest.archivedAt || latest.pendingPermissions?.length ||
@@ -529,6 +550,9 @@ export class Engine {
         const window = sessionWindow(provider, policy);
         if (!window || (usedPct(window) ?? -1) < policy.thresholdPct) continue;
         if (failsOver(agent.id, agent.provider)) continue;
+        // Past the limit notice it is ZeroSub that switches, by its own rule: leave it be
+        // while that rule has an account to move to.
+        if (quotaFailed && accounts?.switchesAtLimit(agent.id, agent.provider)) continue;
         const fetchedAt = timestamp(provider?.fetchedAt ?? own.fetchedAt);
         const windowEnd = timestamp(window.resetsAt);
         if (windowEnd !== null && windowEnd <= this.now() && (fetchedAt === null || fetchedAt <= windowEnd)) continue;

package/server/guard/index.ts

@@ -16,7 +16,7 @@
  *   pass, and gives the lock back once no pause is left waiting on it.
  */
 
-import type { PluginHandlerContext, PluginServerContext } from "@getpaseo/plugin/server";
+import type { PluginHandlerContext, PluginHookContext, PluginServerContext } from "@getpaseo/plugin/server";
 
 import {
   agentStatusRpc,
@@ -44,6 +44,18 @@ import { timelinePublisher } from "./timeline.ts";
 import { withRecordedUsage } from "./usage.ts";
 import { readZeroSub } from "./zerosub.ts";
 import { accountView } from "../../shared/guard/zerosub.ts";
+import { limitNotice, turnRows, type TurnRow } from "../../shared/guard/limit-notice.ts";
+
+/** How many timeline rows to read back for a finished turn's limit notice (as ZeroSub). */
+const NOTICE_ROWS = 40;
+
+/** Whether a finished turn ended on the CLI's limit notice, read from the agent's timeline tail. */
+async function readLimitNotice(context: PluginHookContext, agentId: string, provider: string, turnId: string): Promise<boolean> {
+  if (provider !== "claude" && provider !== "codex") return false;
+  const page = await context.paseo.agents.ref(agentId).timeline.refetch({ direction: "tail", limit: NOTICE_ROWS });
+  const entries = page.entries as unknown as readonly { item: TurnRow; turnId?: string }[];
+  return limitNotice(provider, turnRows(entries, turnId)) !== null;
+}
 
 /** The install id this plugin's own RPCs are reached through. */
 const PLUGIN_ID = "smart-session";
@@ -366,12 +378,24 @@ export function contributeGuard(server: PluginServerContext, options: GuardDepen
   const removeTurnStarted = server.on("agent.turn_started", () => {
     if (governor !== "off") void refresh();
   });
-  const removeTurnEnded = server.on("agent.turn_ended", (event) => {
+  const removeTurnEnded = server.on("agent.turn_ended", (event, context) => {
     if (governor !== "active") return;
     // Never await a governor tick inside a lifecycle hook: cancelAgent itself causes
     // turn_ended, and awaiting both would deadlock.
-    if (!stopped) void engine.turnEnded(event.agent.id, event.turnId, event.outcome.kind).catch(() => undefined);
     if (event.outcome.kind === "failed") engine.quotaFailure(event.agent.id, event.outcome.error.message, event.turnId);
+    // Claude completes a turn at the limit with a notice instead of failing it. Under
+    // ZeroSub, when no account has room, that notice is all there is: read it so the
+    // agent is paused and continued after a reset, and so a pause racing it is kept
+    // rather than cancelled as finished work. Without ZeroSub nothing changes.
+    if (event.outcome.kind === "completed" && event.turnId && engine.accounts && !stopped) {
+      const turnId = event.turnId;
+      void readLimitNotice(context, event.agent.id, event.agent.provider, turnId).catch(() => false).then(async (found) => {
+        if (stopped) return;
+        if (found) engine.limitReached(event.agent.id, turnId);
+        await engine.turnEnded(event.agent.id, turnId, "completed", found).catch(() => undefined);
+        void refresh();
+      });
+    } else if (!stopped) void engine.turnEnded(event.agent.id, event.turnId, event.outcome.kind).catch(() => undefined);
     void refresh();
   });
 

package/shared/guard/limit-notice.ts

@@ -0,0 +1,87 @@
+/**
+ * Whether a finished turn ended on the CLI's limit notice.
+ *
+ * Claude Code does not fail a turn at the limit: it completes it with a synthetic reply,
+ * "You've hit your 5-hour limit · resets 3pm (…)". Paseo reports that as an ordinary
+ * completed turn, so the guard's failed-turn path never sees it. ZeroSub reads the same
+ * reply to fail over (`server/limits.ts` in `@kapybara/zerosub` 1.5.0); when it finds no
+ * account with room it stops there, and nothing continues the agent after the reset
+ * unless Session Guard records a pause. These are ZeroSub's patterns, so the guard
+ * treats exactly the turns ZeroSub treats as limits as limits.
+ *
+ * Only the first line of each candidate counts, and only CLI-generated places are read:
+ * error rows, warning notifications, `[System Error]` replies and, for Claude, the
+ * final two replies. Prose earlier in a turn never matches.
+ */
+
+export interface TurnRow {
+  readonly type: string;
+  readonly text?: string;
+  readonly message?: string;
+  readonly level?: string;
+}
+
+const END = String.raw`(?=\s*(?:·|\.|$))`;
+const APOSTROPHE = "['’]";
+const CLAUDE: readonly RegExp[] = [
+  new RegExp(`^You${APOSTROPHE}ve hit your (?:5-hour |session |weekly |Opus |Sonnet |Fable )?limit${END}`, "i"),
+  new RegExp(`^You${APOSTROPHE}ve reached your (?:Fable|Opus|Sonnet|Haiku)(?: [\\w.]{1,10})? limit${END}`),
+  /Claude AI usage limit reached\|\d{9,}/,
+  new RegExp(
+    `^You${APOSTROPHE}ve hit your (?:usage limit|usage credit limit|team${APOSTROPHE}s shared budget|(?:monthly|individual) spend limit|individual usage limit|(?:org|channel)${APOSTROPHE}s monthly (?:usage|spend) limit)${END}`,
+    "i",
+  ),
+  new RegExp(`^You${APOSTROPHE}re out of (?:usage credits|extra usage)${END}`, "i"),
+  /^Your org is out of usage\s*·/i,
+];
+const CODEX: readonly RegExp[] = [
+  new RegExp(`^You${APOSTROPHE}ve hit your usage limit\\b`, "i"),
+  /^The usage limit has been reached\b/i,
+  /"type"\s*:\s*"usage_limit_reached"/,
+  /^Your workspace is out of credits\b/i,
+  /^You hit your spend cap\b/i,
+];
+
+const SYSTEM_ERROR = /^\[System Error\]\s*/;
+const MAX_NOTICE = 400;
+const clean = (text: string) => text.replace(SYSTEM_ERROR, "").replace(/^API Error:\s*/i, "").trim();
+const firstLine = (text: string) => (text.split("\n")[0] ?? text).trim();
+
+/** The limit notice a finished turn ended on, given that turn's rows oldest first; null when none. */
+export function limitNotice(provider: string, rows: readonly TurnRow[]): string | null {
+  const patterns = provider === "claude" ? CLAUDE : provider === "codex" ? CODEX : null;
+  if (!patterns) return null;
+  const found: string[] = [];
+  let replies = 0;
+  for (let index = rows.length - 1; index >= 0; index -= 1) {
+    const row = rows[index]!;
+    if (row.type === "user_message") break;
+    if (row.type === "error" && row.message) found.push(row.message);
+    else if (row.type === "notification" && row.level !== "info" && row.message) found.push(row.message);
+    else if (row.type === "assistant_message" && typeof row.text === "string") {
+      if (SYSTEM_ERROR.test(row.text) || (provider === "claude" && replies < 2)) found.push(row.text);
+      replies += 1;
+    }
+  }
+  for (const text of found.map(clean)) {
+    if (text.length === 0 || text.length > MAX_NOTICE) continue;
+    const line = firstLine(text);
+    if (patterns.some((pattern) => pattern.test(provider === "claude" ? line : text))) return line;
+  }
+  return null;
+}
+
+/**
+ * One turn's rows from a tail page of the agent's timeline, oldest first. Providers can
+ * reuse a turn id, so reading back from the turn's last row, another turn's prompt is
+ * where this one began (as ZeroSub's `turnRows`).
+ */
+export function turnRows<T extends TurnRow>(entries: readonly { item: T; turnId?: string }[], turnId: string): T[] {
+  const rows: T[] = [];
+  for (let index = entries.length - 1; index >= 0; index -= 1) {
+    const entry = entries[index]!;
+    if (entry.turnId === turnId) rows.push(entry.item);
+    else if (rows.length > 0 && entry.turnId && entry.item.type === "user_message") break;
+  }
+  return rows.reverse();
+}

package/shared/guard/zerosub.ts

@@ -174,22 +174,63 @@ const limited = (account: ZeroSubAccount, now: number) => {
 
 /**
  * One account's usage as a provider row the guard reads, or an unavailable row when
- * there is no trustworthy reading. A limit the CLI reported is the freshest word on a
- * window, so it shows as full until it lifts.
+ * there is no trustworthy reading. Whether the account is out is `withOut`'s job.
  */
-export function accountUsage(snapshot: ZeroSubSnapshot, account: ZeroSubAccount, now: number): ProviderUsage {
+export function accountUsage(snapshot: ZeroSubSnapshot, account: ZeroSubAccount): ProviderUsage {
   const reading = snapshot.readings[account.id];
   if (!reading || reading.windows.length === 0) return { providerId: account.family, status: "unavailable", fetchedAt: null, windows: [] };
-  const full = limited(account, now) && account.limitKind === "window";
   const windows: UsageWindow[] = reading.windows.map((window) => ({
     id: paseoWindowId(account.family, window),
-    usedPct: full ? Math.max(100, window.usedPct) : window.usedPct,
+    usedPct: window.usedPct,
     remainingPct: null,
     resetsAt: window.resetsAt,
   }));
   return { providerId: account.family, status: "available", fetchedAt: reading.fetchedAt, windows };
 }
 
+const pctOf = (window: UsageWindow): number | null =>
+  typeof window.usedPct === "number" ? window.usedPct : typeof window.remainingPct === "number" ? 100 - window.remainingPct : null;
+
+/**
+ * When an account is out, the time it gets room again (ms); null while it has room.
+ *
+ * Out means ZeroSub recorded a limit on it (the CLI's notice, or a full reading), or a
+ * window it reads that has not rolled over yet is full. That includes the weekly
+ * window: the session window the guard watches can show room while the account is
+ * out for days. A recorded budget limit counts too: the account takes no turn.
+ */
+function outUntil(row: ProviderUsage, account: ZeroSubAccount, now: number): number | null {
+  const ends: number[] = [];
+  const until = time(account.limitedUntil);
+  if (until !== null && until > now) ends.push(until);
+  for (const window of row.status === "available" ? row.windows : []) {
+    const resets = time(window.resetsAt);
+    if (resets !== null && resets <= now) continue; // Rolled over since that reading.
+    if ((pctOf(window) ?? 0) >= 100) ends.push(resets ?? now);
+  }
+  return ends.length ? Math.max(...ends) : null;
+}
+
+/**
+ * An out account's row, with the guard's session windows shown full until it gets room
+ * again. The guard pauses and anchors on its session window alone, so this is how an
+ * account out on another window, or at a limit no reading shows yet, reads as out; the
+ * anchor is when the account as a whole has room again.
+ */
+function withOut(row: ProviderUsage, account: ZeroSubAccount, now: number, sessionWindowIds: readonly string[]): ProviderUsage {
+  const until = outUntil(row, account, now);
+  if (until === null || row.status !== "available") return row;
+  let changed = false;
+  const windows = row.windows.map((window) => {
+    const resets = time(window.resetsAt);
+    // Already full until the account has room again: the reading says so itself.
+    if (!sessionWindowIds.includes(window.id) || ((pctOf(window) ?? 0) >= 100 && resets !== null && resets >= until)) return window;
+    changed = true;
+    return { ...window, usedPct: Math.max(100, pctOf(window) ?? 100), remainingPct: null, resetsAt: new Date(Math.max(until, resets ?? 0)).toISOString() };
+  });
+  return changed ? { ...row, windows } : row;
+}
+
 /**
  * Whether an account could take an agent right now: usable by ZeroSub's own rules
  * (signed in, not set aside, no recorded limit) and, stricter than ZeroSub, with a
@@ -214,12 +255,32 @@ export function accountsWithRoom(snapshot: ZeroSubSnapshot, current: ZeroSubAcco
     account.family === current.family && account.id !== current.id && hasRoom(snapshot, account, thresholdPct, sessionWindowIds, now)).length;
 }
 
+/**
+ * Whether ZeroSub would move the agent to another account at the limit, by ZeroSub's
+ * own rule (`isUsable` in its routing): automatic switching on and another account of
+ * the provider signed in, not set aside and with no recorded limit. Looser than
+ * `hasRoom`, deliberately: once the CLI has reported the limit it is ZeroSub that
+ * decides, and this is what it decides with.
+ */
+export function switchesAtLimit(snapshot: ZeroSubSnapshot, current: ZeroSubAccount, now: number): boolean {
+  return snapshot.autoSwitch && snapshot.accounts.some((account) =>
+    account.family === current.family && account.id !== current.id && account.signedIn && !account.disabled && !limited(account, now));
+}
+
 /** The view Session Guard's engine asks, once per pass. */
 export interface AccountView {
-  /** Usage as the agent's own account sees it. */
+  /** Usage as the agent's own account sees it, with an out account's session windows shown full. */
   usageFor(agentId: string, provider: string): Usage;
   /** ZeroSub will move this agent to another account with room when its account hits the limit. */
   failsOver(agentId: string, provider: string): boolean;
+  /** After the CLI reported the limit: ZeroSub is moving this agent to another account itself. */
+  switchesAtLimit(agentId: string, provider: string): boolean;
+  /**
+   * Whether an account this agent can use has room, shown by a reading taken after
+   * `since` (a pause): its own account, or — when ZeroSub would fail it over there —
+   * another one. Null while every account is still out.
+   */
+  roomSince(agentId: string, provider: string, since: number): "own" | "elsewhere" | null;
   /** ZeroSub already carries this agent's Codex task on in another tab. */
   continuedElsewhere(agentId: string): boolean;
 }
@@ -230,19 +291,40 @@ export function accountView(
   policy: { thresholdPct: number; windowIds: readonly string[] },
   now: number,
 ): AccountView {
+  const roomAfter = (account: ZeroSubAccount, since: number) => {
+    const fetched = time(snapshot.readings[account.id]?.fetchedAt);
+    return fetched !== null && fetched > since && hasRoom(snapshot, account, policy.thresholdPct, policy.windowIds, now);
+  };
   return {
     usageFor(agentId, provider) {
       const account = accountOf(snapshot, agentId, provider);
-      // The CLI login is what Paseo and the recorder already measure, and measure more often.
-      if (!account || account.kind === "main") return usage;
-      const own = accountUsage(snapshot, account, now);
-      return { ...usage, providers: [...usage.providers.filter((p) => p.providerId !== provider), { ...own, providerId: provider }] };
+      if (!account) return usage;
+      // The CLI login is what Paseo and the recorder already measure, and measure more
+      // often; ZeroSub only adds a limit it recorded on it.
+      const own = account.kind === "main"
+        ? usage.providers.find((p) => p.providerId === provider)
+        : { ...accountUsage(snapshot, account), providerId: provider };
+      if (!own) return usage;
+      const shown = withOut(own, account, now, policy.windowIds);
+      if (shown === own && account.kind === "main") return usage;
+      return { ...usage, providers: [...usage.providers.filter((p) => p.providerId !== provider), shown] };
     },
     failsOver(agentId, provider) {
       if (!snapshot.autoSwitch) return false;
       const account = accountOf(snapshot, agentId, provider);
       return account !== null && accountsWithRoom(snapshot, account, policy.thresholdPct, policy.windowIds, now) > 0;
     },
+    switchesAtLimit(agentId, provider) {
+      const account = accountOf(snapshot, agentId, provider);
+      return account !== null && switchesAtLimit(snapshot, account, now);
+    },
+    roomSince(agentId, provider, since) {
+      const account = accountOf(snapshot, agentId, provider);
+      if (!account) return null;
+      if (roomAfter(account, since)) return "own";
+      if (!snapshot.autoSwitch) return null;
+      return snapshot.accounts.some((other) => other.family === account.family && other.id !== account.id && roomAfter(other, since)) ? "elsewhere" : null;
+    },
     continuedElsewhere: (agentId) => snapshot.continuedElsewhere.has(agentId),
   };
 }