@buoy-gg/agent-core 7.0.41 → 7.0.43

package/lib/commonjs/catalog/catalog.source.json

@@ -2515,6 +2515,255 @@
     ],
     "unavailableWhen": "The `@buoy-gg/time-machine` tool is not in the app's FloatingDevTools tool list, or the app is a release build that has not opted into `externalSync.enableInRelease` with a real Pro license (packages/devtools-floating-menu/src/floatingMenu/autoExternalSync.tsx:190 — no socket, so no action reaches the device at all). Individual state sources are also absent unless their tool package is installed and instrumented: check `providers[].canCapture`/`canRestore` from `list` before assuming a source is covered."
   },
+  {
+    "toolId": "clock",
+    "title": "Clock",
+    "summary": "Override the app's own clock without touching the device: move it to any date (setTime), jump it forward or back (shift), stop it (freeze/resume), run it faster (setRate), or go back to real time (reset). Reach for it to test anything time-based on the client: expired offers and coupons, countdowns, trial and renewal dates, day or month rollovers, 'last seen' labels, token expiry the app checks itself. What moves: Date.now(), new Date(), Date() and Intl.DateTimeFormat format() with no date; a forward shift also runs the app's setTimeout/setInterval callbacks that come due inside the jump, once each. What stays real: performance.now(), animations, native timers and scheduled notifications, the time zone, and the backend's clock, so a server that checks expiry itself still uses real time. Values the app computed before the change keep their old time until the screen re-reads the clock or the app reloads (the override survives reloads). It also reads the app's sign-in tokens from Network's captured requests (JWTs, PASETO, opaque tokens whose login response gave an expiry, session cookies) and tests the app's token refresh: jumpToTokenExpiry for apps that refresh before expiry, failNextRequest for apps that refresh after a 401. Raw tokens are never returned. Every action returns the same state object as getState: { mode:'real'|'running'|'frozen', active, rate, virtualNow, virtualIso, realNow, offsetMs, timeZone, timers:{total,timeouts,intervals,nextTimeoutInMs}, lastJump:{byMs,firedTimers,at}|null, settings:{persist,showChip,fireTimersOnJump}, tokens:{available, tokens:[{id,label,host,formatLabel,hint,claims,expiresAt,serverExpiresAt,expirySource,lifetimeMs,issuedBy,refresh,uses,refreshes,looping,expiredSends,rejected}], check:{kind:'expiry'|'401',tokenId,status:'waiting'|'refreshed'|'loop',forcedAt,refreshedAt,newLifetimeMs,newIssuedBy,newTokens,staleAfterFailure}|null}, patched:{date,intl,timers,animatedOnRealClock} }. expiresAt is on the app's clock; serverExpiresAt on real time.",
+    "unavailableWhen": "Needs @buoy-gg/clock installed (FloatingDevTools auto-discovers it). In release builds the saved override and timer tracking load when the Clock tool is first opened rather than at app start.",
+    "actions": [
+      {
+        "action": "getState",
+        "summary": "Read what the app's clock says right now, how far it is from real time, and the pending timers.",
+        "description": "Returns the state object described in the tool summary. Read virtualIso (the app's time) against realNow before reporting what 'now' is for the app; offsetMs is app minus real. mode 'real' means no override is on. timers counts the app's pending setTimeout/setInterval callbacks, which is how many a forward shift could run.",
+        "effect": "read",
+        "release": "works",
+        "params": {
+          "type": "object",
+          "properties": {},
+          "additionalProperties": false
+        }
+      },
+      {
+        "action": "setTime",
+        "summary": "Move the app's clock to `time` (ISO 8601, epoch ms, or relative like \"+3d\"); pass `freeze` true to stop it there.",
+        "description": "`time` accepts \"2026-12-31T23:59:50\" (device-local when no zone is given), \"2026-12-31 23:59\", \"2026-12-31T23:59:50Z\", epoch milliseconds, or a signed duration from the app's current time (\"+30d\", \"-2h\"). The clock keeps running from there at the current speed unless `freeze` is true. Unlike shift, setTime never runs timers. Throws a message naming the accepted formats when `time` cannot be read. Returns the new state.",
+        "effect": "write",
+        "release": "works",
+        "undo": {
+          "action": "reset",
+          "note": "reset returns to the device's real clock. If an override was already on before this call, reset does not bring that one back: read getState first and set it again with setTime/setRate."
+        },
+        "params": {
+          "type": "object",
+          "properties": {
+            "time": {
+              "type": [
+                "string",
+                "number"
+              ],
+              "description": "Target time: ISO 8601 (\"2026-12-31T23:59:50\"), \"YYYY-MM-DD HH:MM\", epoch ms, or relative (\"+1d\", \"-2h\")."
+            },
+            "freeze": {
+              "type": "boolean",
+              "description": "Stop the clock at `time` instead of letting it run. Default false."
+            }
+          },
+          "required": [
+            "time"
+          ],
+          "additionalProperties": false
+        }
+      },
+      {
+        "action": "shift",
+        "summary": "Jump the app's clock `by` a duration (\"+1d\", \"-2h30m\", \"90s\" or ms); forward jumps also run app timers that come due unless `fireTimers` is false.",
+        "description": "Moves the clock relative to what it reads now; a frozen clock stays frozen. Units: ms, s, m, h, d, w, mo (30 days), y (365 days). A forward jump runs, once each and soonest first, every app setTimeout/setInterval callback due within the jump (Playwright fastForward rules) and shortens what is left of the others; lastJump.firedTimers reports how many ran. Buoy's own timers are never run. Backward jumps never run timers. Returns the new state.",
+        "effect": "write",
+        "release": "works",
+        "undo": {
+          "action": "reset",
+          "note": "reset returns to the device's real clock. If an override was already on before this call, reset does not bring that one back: read getState first and set it again with setTime/setRate."
+        },
+        "params": {
+          "type": "object",
+          "properties": {
+            "by": {
+              "type": [
+                "string",
+                "number"
+              ],
+              "description": "Signed duration: \"+1d\", \"-2h30m\", \"90s\", \"1.5 hours\", or a number of ms."
+            },
+            "fireTimers": {
+              "type": "boolean",
+              "description": "Run app timers that come due inside a forward jump. Default: the fireTimersOnJump setting (on)."
+            }
+          },
+          "required": [
+            "by"
+          ],
+          "additionalProperties": false
+        }
+      },
+      {
+        "action": "freeze",
+        "summary": "Stop the app's clock where it is, or at `time` if given.",
+        "description": "The app reads the same instant until resume, shift, setTime or reset. Timers keep running in real time and animations keep moving; only reads of the time stop. `time` takes the same formats as setTime. Returns the new state.",
+        "effect": "write",
+        "release": "works",
+        "undo": {
+          "action": "resume",
+          "note": "resume starts the clock again from the frozen instant; it does not return to the time before the freeze. Use reset for real time."
+        },
+        "params": {
+          "type": "object",
+          "properties": {
+            "time": {
+              "type": [
+                "string",
+                "number"
+              ],
+              "description": "Optional instant to freeze at (same formats as setTime). Omit to freeze at the current app time."
+            }
+          },
+          "additionalProperties": false
+        }
+      },
+      {
+        "action": "resume",
+        "summary": "Start a frozen app clock again from the instant it was frozen at.",
+        "description": "No-op when the clock is not frozen. The clock continues at its current speed. Returns the new state.",
+        "effect": "write",
+        "release": "works",
+        "undo": {
+          "action": "freeze",
+          "note": "freeze stops it again, at the current app time."
+        },
+        "params": {
+          "type": "object",
+          "properties": {},
+          "additionalProperties": false
+        }
+      },
+      {
+        "action": "setRate",
+        "summary": "Run the app's clock `rate` times as fast as real time (1 = normal, 60 = a minute per second, 3600 = an hour per second).",
+        "description": "Starts from what the app's clock reads now, so nothing jumps. Only reads of the time speed up: timer delays stay real, so taps, animations and polling behave; code that recomputes from Date.now() on each tick (most countdowns) shows the faster time. Range 0.1 to 86400. Returns the new state.",
+        "effect": "write",
+        "release": "works",
+        "undo": {
+          "action": "setRate",
+          "note": "Call again with rate 1. That keeps the time already gained; use reset for real time."
+        },
+        "params": {
+          "type": "object",
+          "properties": {
+            "rate": {
+              "type": "number",
+              "description": "Speed multiplier, 0.1-86400. 1 is normal speed."
+            }
+          },
+          "required": [
+            "rate"
+          ],
+          "additionalProperties": false
+        }
+      },
+      {
+        "action": "reset",
+        "summary": "Put the app back on the device's real clock.",
+        "description": "Removes the Date and Intl patches entirely, clears the saved override and closes the clock chip. Screens that already computed a time keep it until they re-read the clock or the app reloads. Returns the new state (mode 'real').",
+        "effect": "write",
+        "release": "works",
+        "params": {
+          "type": "object",
+          "properties": {},
+          "additionalProperties": false
+        }
+      },
+      {
+        "action": "updateSettings",
+        "summary": "Change the Clock tool's settings: `persist` (keep the override across reloads), `showChip` (floating reminder), `fireTimersOnJump`.",
+        "description": "Only the booleans given are changed. persist=false still applies the override now but forgets it on the next reload. Returns the new state with settings.",
+        "effect": "write",
+        "release": "works",
+        "params": {
+          "type": "object",
+          "properties": {
+            "persist": {
+              "type": "boolean",
+              "description": "Keep the override across reloads and restarts."
+            },
+            "showChip": {
+              "type": "boolean",
+              "description": "Show the floating clock chip while an override is on."
+            },
+            "fireTimersOnJump": {
+              "type": "boolean",
+              "description": "Whether forward shifts run app timers that come due."
+            }
+          },
+          "additionalProperties": false
+        }
+      },
+      {
+        "action": "jumpToTokenExpiry",
+        "summary": "Move the app's clock to just before a sign-in token expires (default 10 s before), then watch for the app to fetch a new token.",
+        "description": "Tests apps that refresh their token before it expires by comparing its expiry with Date.now(). Shifts the app's clock forward (running timers that come due, like a scheduled refresh) to `leadMs` before the token's expiry, and starts a refresh check. The server keeps real time, so it still accepts the old token: only the app's own refresh logic is exercised. The app has to send a request (or run its refresh timer) before a new token shows up; read getState's tokens.check for the result: 'refreshed' with the new token's lifetime and issuing endpoint, or 'loop' when new tokens keep arriving because they already look expired to the moved clock. Throws when no token has been seen, when the token's expiry is unreadable (then use failNextRequest), or when it has already expired on the app's clock.",
+        "effect": "write",
+        "release": "works",
+        "undo": {
+          "action": "reset",
+          "note": "reset puts the app back on real time. The app keeps any token it fetched meanwhile, which is harmless."
+        },
+        "params": {
+          "type": "object",
+          "properties": {
+            "token": {
+              "type": "string",
+              "description": "Token id from getState's tokens[].id. Default: the most recently used token that has a readable expiry."
+            },
+            "leadMs": {
+              "type": "number",
+              "description": "Land this many ms before expiry. Default 10000."
+            }
+          },
+          "additionalProperties": false
+        }
+      },
+      {
+        "action": "failNextRequest",
+        "summary": "Answer the app's next request that carries a sign-in token with a 401 (or `status` 403), once or `times` times, then watch for the app to fetch a new token.",
+        "description": "Tests apps that refresh their token after the server rejects it. Adds a one-shot Network override on the token's origin, limited to requests that send the token's header, so the 401 never lands on the app's own token request. It answers with `WWW-Authenticate: Bearer error=\"invalid_token\"` and an invalid_token JSON body, and starts a refresh check. Needs @buoy-gg/network. The app has to send a request for the 401 to reach it; getState's tokens.check then shows forcedAt, whether a new token arrived, staleAfterFailure (requests that re-sent the old token after the 401) and failedRefreshes (token requests that failed). Replaces an earlier 401 that has not fired yet.",
+        "effect": "write",
+        "release": "works",
+        "undo": {
+          "action": "stopTokenCheck",
+          "note": "stopTokenCheck withdraws the 401 if it has not reached the app yet. A 401 the app already received cannot be taken back."
+        },
+        "params": {
+          "type": "object",
+          "properties": {
+            "token": {
+              "type": "string",
+              "description": "Token id from getState's tokens[].id. Default: the most recently used token that has a readable expiry."
+            },
+            "status": {
+              "type": "number",
+              "description": "401 (default) or 403."
+            },
+            "times": {
+              "type": "number",
+              "description": "How many requests to fail, 1-10. Default 1."
+            }
+          },
+          "additionalProperties": false
+        }
+      },
+      {
+        "action": "stopTokenCheck",
+        "summary": "End the refresh check, withdrawing a forced 401 that has not reached the app yet.",
+        "description": "Clears tokens.check. When the check was started by failNextRequest and the 401 has not fired, removes that Network override so it cannot fail a later request. Returns the new state.",
+        "effect": "write",
+        "release": "works",
+        "params": {
+          "type": "object",
+          "properties": {},
+          "additionalProperties": false
+        }
+      }
+    ]
+  },
   {
     "toolId": "storage",
     "title": "Storage",

package/lib/commonjs/catalog/catalog.types.g.js

@@ -1,46 +1 @@
-"use strict";
-
-Object.defineProperty(exports, "__esModule", {
-  value: true
-});
-exports.CATALOG_ACTIONS = void 0;
-/**
- * GENERATED by scripts/gen-agent-catalog.mjs — do not edit.
- * Source: packages/agent-core/src/catalog/catalog.source.json
- *
- * The catalog's tool ids and action names as types, so a wrong name fails
- * at compile time. `catalog.g.ts` carries the data.
- *
- * 26 Buoy tools, 218 actions.
- */
-
-/** Action names per tool — the runtime mirror of {@link CatalogActionMap}. */
-const CATALOG_ACTIONS = exports.CATALOG_ACTIONS = {
-  "env": ["getSnapshot"],
-  "console": ["getSnapshot", "clearEntries"],
-  "sentry": ["getSnapshot", "clearEnvelopes"],
-  "jotai": ["listAtoms", "getAtomValue", "getChangeDetail", "setAtom", "clearEvents"],
-  "route-events": ["getSnapshot", "getCurrentRoute", "navigate", "stackGoBack", "stackNavigateToIndex", "stackPopToIndex", "stackPopToTop", "clearEvents"],
-  "debug-borders": ["cycleMode", "setMode"],
-  "zustand": ["listStores", "getStoreState", "getChangeDetail", "setState", "rehydrate", "clearEvents"],
-  "redux": ["getState", "getActionDetail", "dispatch", "clearEvents"],
-  "impersonate": ["searchUsers", "startImpersonation", "stopImpersonation", "pauseImpersonation", "resumeImpersonation", "updateSettings", "removeFromHistory", "clearHistory"],
-  "query": ["listQueries", "getQueryData", "refetch", "invalidate", "reset", "remove", "setQueryData", "triggerError", "restoreError", "triggerLoading", "restoreLoading", "clearQueryCache", "clearMutationCache", "setOnline"],
-  "events": ["exportEvents", "setEnabledSources", "clearEvents"],
-  "network": ["getSnapshot", "getCaptureStatus", "getEventBody", "setPinned", "setSaved", "removeSavedRecord", "clearSavedRequests", "clearPinnedRequests", "clearEvents", "listOverrideRules", "getOverrideRuleBody", "debugOverrides", "upsertOverrideRule", "setOverrideRuleEnabled", "setOverridesEnabled", "deleteOverrideRule", "clearOverrideRules", "getNetworkConditions", "setNetworkConditions"],
-  "js-top": ["sample", "getOriginDetail", "setEnabled", "pause", "resume", "clear"],
-  "app": ["ping", "reloadApp"],
-  "time-machine": ["list", "capture", "captureBaseline", "wipeAll", "restore", "preview", "inspect", "delete", "rename", "duplicate", "setExclusions", "setScope", "setRestoreRoute"],
-  "storage": ["getRequiredKeys", "async.getAllKeys", "async.multiGet", "async.getItem", "async.setItem", "async.removeItem", "async.multiRemove", "async.multiSet", "async.clear", "clearAppStorage", "getEventDetail", "clearEvents", "timeTravel.undo", "timeTravel.jump", "mmkv.snapshot", "mmkv.get", "mmkv.set", "mmkv.remove", "secure.keys", "secure.snapshot", "secure.get", "secure.set", "secure.delete"],
-  "highlight-updates": ["describeScreen", "tapElement", "waitFor", "beginMeasurement", "endMeasurement", "locateComponent", "getRenderDetail", "setEnabled", "toggle", "setSilentTracking", "toggleFreeze", "setSpotlight", "clearRenderCounts", "startTouchCapture", "stopTouchCapture", "clearTouchCapture", "readTouchCapture"],
-  "scenarios": ["listScenarios", "getScenario", "save", "acceptDraft", "discardDraft", "preview", "run", "deactivate", "delete", "setFolder", "listFolders", "getActive", "export"],
-  "perf-monitor": ["setEnabled", "startRecording", "stopRecording", "savePending", "discardPending", "mark", "startAutomation", "cancelAutomation", "acknowledgeAutomation", "refreshIndex", "getAutomationConfig", "setAutomationConfig", "loadReport", "deleteReport", "deleteBatch", "clearAll"],
-  "assets": ["list", "getDetail", "rescan", "measureSizes", "saveBaseline", "clearBaseline", "getDiff", "clearRecords", "getScanStatus"],
-  "tv-remote": ["arm", "getEventsSince", "setMenuCapture", "disarm", "clear"],
-  "focus-inspector": ["rescan", "focusElement", "setTracking", "clearHistory"],
-  "images": ["list", "getDetail", "getCaptureStatus", "retry", "flash", "proveSavings", "setOverride", "clearOverride", "setNetworkMode", "setBlankImages", "hardReload", "evictDisk", "massAction", "clearRecords", "clearExpoCaches"],
-  "ask-buoy": ["listChanges", "undoAll", "retrieve", "openProcedure"],
-  "push-notifications": ["getSnapshot", "getCapabilities", "getEvent", "getPermissions", "listPresented", "refreshToken", "setCaptureSession", "clearCapturedEvents", "scheduleLocal"],
-  "image-overlay": ["getSnapshot", "listTargets", "selectTarget", "loadImage", "setSettings", "fitToScreen", "resetSettings", "remove"]
-};
-//# sourceMappingURL=catalog.types.g.js.map
+"use strict";Object.defineProperty(exports,"__esModule",{value:true});exports.CATALOG_ACTIONS=void 0;const CATALOG_ACTIONS=exports.CATALOG_ACTIONS={"env":["getSnapshot"],"console":["getSnapshot","clearEntries"],"sentry":["getSnapshot","clearEnvelopes"],"jotai":["listAtoms","getAtomValue","getChangeDetail","setAtom","clearEvents"],"route-events":["getSnapshot","getCurrentRoute","navigate","stackGoBack","stackNavigateToIndex","stackPopToIndex","stackPopToTop","clearEvents"],"debug-borders":["cycleMode","setMode"],"zustand":["listStores","getStoreState","getChangeDetail","setState","rehydrate","clearEvents"],"redux":["getState","getActionDetail","dispatch","clearEvents"],"impersonate":["searchUsers","startImpersonation","stopImpersonation","pauseImpersonation","resumeImpersonation","updateSettings","removeFromHistory","clearHistory"],"query":["listQueries","getQueryData","refetch","invalidate","reset","remove","setQueryData","triggerError","restoreError","triggerLoading","restoreLoading","clearQueryCache","clearMutationCache","setOnline"],"events":["exportEvents","setEnabledSources","clearEvents"],"network":["getSnapshot","getCaptureStatus","getEventBody","setPinned","setSaved","removeSavedRecord","clearSavedRequests","clearPinnedRequests","clearEvents","listOverrideRules","getOverrideRuleBody","debugOverrides","upsertOverrideRule","setOverrideRuleEnabled","setOverridesEnabled","deleteOverrideRule","clearOverrideRules","getNetworkConditions","setNetworkConditions"],"js-top":["sample","getOriginDetail","setEnabled","pause","resume","clear"],"app":["ping","reloadApp"],"time-machine":["list","capture","captureBaseline","wipeAll","restore","preview","inspect","delete","rename","duplicate","setExclusions","setScope","setRestoreRoute"],"clock":["getState","setTime","shift","freeze","resume","setRate","reset","updateSettings","jumpToTokenExpiry","failNextRequest","stopTokenCheck"],"storage":["getRequiredKeys","async.getAllKeys","async.multiGet","async.getItem","async.setItem","async.removeItem","async.multiRemove","async.multiSet","async.clear","clearAppStorage","getEventDetail","clearEvents","timeTravel.undo","timeTravel.jump","mmkv.snapshot","mmkv.get","mmkv.set","mmkv.remove","secure.keys","secure.snapshot","secure.get","secure.set","secure.delete"],"highlight-updates":["describeScreen","tapElement","waitFor","beginMeasurement","endMeasurement","locateComponent","getRenderDetail","setEnabled","toggle","setSilentTracking","toggleFreeze","setSpotlight","clearRenderCounts","startTouchCapture","stopTouchCapture","clearTouchCapture","readTouchCapture"],"scenarios":["listScenarios","getScenario","save","acceptDraft","discardDraft","preview","run","deactivate","delete","setFolder","listFolders","getActive","export"],"perf-monitor":["setEnabled","startRecording","stopRecording","savePending","discardPending","mark","startAutomation","cancelAutomation","acknowledgeAutomation","refreshIndex","getAutomationConfig","setAutomationConfig","loadReport","deleteReport","deleteBatch","clearAll"],"assets":["list","getDetail","rescan","measureSizes","saveBaseline","clearBaseline","getDiff","clearRecords","getScanStatus"],"tv-remote":["arm","getEventsSince","setMenuCapture","disarm","clear"],"focus-inspector":["rescan","focusElement","setTracking","clearHistory"],"images":["list","getDetail","getCaptureStatus","retry","flash","proveSavings","setOverride","clearOverride","setNetworkMode","setBlankImages","hardReload","evictDisk","massAction","clearRecords","clearExpoCaches"],"ask-buoy":["listChanges","undoAll","retrieve","openProcedure"],"push-notifications":["getSnapshot","getCapabilities","getEvent","getPermissions","listPresented","refreshToken","setCaptureSession","clearCapturedEvents","scheduleLocal"],"image-overlay":["getSnapshot","listTargets","selectTarget","loadImage","setSettings","fitToScreen","resetSettings","remove"]};