@quiesco/agent 0.0.0-stage → 0.1.0

package/src/sync/offline.ts

@@ -0,0 +1,121 @@
+/**
+ * Simulated offline mode (Phase 6.6 `app.device.setNetwork('offline')`; HU 2026-11-09: the agent blocks the
+ * app's connections on every platform, Android / the web also cut the device's network). While offline,
+ * the app's new fetch / XMLHttpRequest / WebSocket connections are sent to a host that never resolves
+ * (`.invalid`, RFC 6761), so they fail the way that platform fails without a network — React Native's
+ * "Network request failed", a browser's "Failed to fetch", a WebSocket error and close — instead of with
+ * made-up errors. Connections already open stay open. The agent's own connection is exempt.
+ *
+ * Installed before the network tracker, which wraps these patches and so still reports (and waits for)
+ * the URL the app asked for.
+ */
+import { isFunction, patch } from './tracker';
+
+/** Where blocked requests go: a name no resolver answers (RFC 6761 `.invalid`). */
+export const OFFLINE_HTTP_URL = 'http://offline.quiesco.invalid/';
+export const OFFLINE_WS_URL = 'ws://offline.quiesco.invalid/';
+
+export type FetchFn = (this: unknown, input: unknown, init?: unknown) => Promise<unknown>;
+type OpenFn = (this: unknown, method: string, url: string | URL, ...rest: unknown[]) => unknown;
+type SocketCtor = new (url: string | URL, ...rest: unknown[]) => object;
+
+export interface OfflineGlobals {
+  fetch?: FetchFn;
+  XMLHttpRequest?: { prototype: { open: OpenFn } };
+  WebSocket?: SocketCtor;
+}
+
+function urlOf(input: unknown): string {
+  if (typeof input === 'string') return input;
+  if (typeof input === 'object' && input !== null) {
+    const u = (input as { url?: unknown; href?: unknown }).url ?? (input as { href?: unknown }).href;
+    if (typeof u === 'string') return u;
+  }
+  return String(input);
+}
+
+/** `host:port` of an absolute URL (lower case, default ports left out as written), else null. */
+export function hostOf(url: string): string | null {
+  const m = /^[a-z][a-z0-9+.-]*:\/\/(?:[^@/?#]*@)?([^/?#]+)/i.exec(url);
+  return m === null ? null : (m[1] as string).toLowerCase();
+}
+
+/** Exempts the agent's own connection, `ws://localhost:<port>` (also reached as 127.0.0.1). */
+export function ownConnection(port: number | string): (url: string) => boolean {
+  const own = new Set([`localhost:${port}`, `127.0.0.1:${port}`]);
+  return (url) => {
+    const h = hostOf(url);
+    return h !== null && own.has(h);
+  };
+}
+
+export class OfflineGate {
+  private offline = false;
+  private exempt: (url: string) => boolean = () => false;
+  private readonly restores: (() => void)[] = [];
+
+  constructor(private readonly target: OfflineGlobals = globalThis as unknown as OfflineGlobals) {}
+
+  get isOffline(): boolean {
+    return this.offline;
+  }
+
+  /** Applies to connections opened from now on. */
+  setOffline(offline: boolean): void {
+    this.offline = offline;
+  }
+
+  /** URLs that keep working offline (the agent's own connection). */
+  setExempt(exempt: (url: string) => boolean): void {
+    this.exempt = exempt;
+  }
+
+  blocks(url: string): boolean {
+    return this.offline && !this.exempt(url);
+  }
+
+  /** A fetch function that is blocked like the global one (used for `expo/fetch` imported directly). */
+  wrapFetch(original: FetchFn): FetchFn {
+    const self = this;
+    return function (this: unknown, input: unknown, init?: unknown) {
+      if (!self.blocks(urlOf(input))) return original.call(this, input, init);
+      // A Request object carries its method and signal; its body is irrelevant, the request fails.
+      const req = typeof input === 'object' && input !== null && typeof (input as { url?: unknown }).url === 'string' ? (input as { method?: unknown; signal?: unknown }) : null;
+      const merged = req === null ? init : { method: req.method, ...(req.signal !== undefined ? { signal: req.signal } : {}), ...(init as object | undefined) };
+      return original.call(this, OFFLINE_HTTP_URL, merged);
+    } as FetchFn;
+  }
+
+  install(): void {
+    if (this.restores.length > 0) return;
+    const self = this;
+    if (isFunction(this.target.fetch)) {
+      this.restores.push(patch(this.target, 'fetch', (original) => this.wrapFetch(original as FetchFn)));
+    }
+    const proto = this.target.XMLHttpRequest?.prototype;
+    if (proto !== undefined && isFunction(proto.open)) {
+      this.restores.push(
+        patch(proto, 'open', (original) =>
+          function (this: unknown, method: string, url: string | URL, ...rest: unknown[]) {
+            return original.call(this, method, self.blocks(urlOf(url)) ? OFFLINE_HTTP_URL : url, ...rest);
+          },
+        ),
+      );
+    }
+    const WS = this.target.WebSocket;
+    if (isFunction(WS)) {
+      // A subclass keeps `instanceof WebSocket`, the static constants and the app's event handlers.
+      const Offline = class extends WS {
+        constructor(url: string | URL, ...rest: unknown[]) {
+          super(self.blocks(urlOf(url)) ? OFFLINE_WS_URL : url, ...rest);
+        }
+      };
+      Object.defineProperty(Offline, 'name', { value: WS.name });
+      this.restores.push(patch(this.target, 'WebSocket', () => Offline as SocketCtor));
+    }
+  }
+
+  uninstall(): void {
+    while (this.restores.length > 0) this.restores.pop()?.();
+  }
+}

package/src/sync/react.ts

@@ -0,0 +1,28 @@
+/**
+ * React idle (requirements.md §6.2-3; docs/spikes/02-react-idle.md): no pending work on any FiberRoot
+ * (detector A) AND no unfinished scheduler task (detector B). The hook and scheduler patch are
+ * installed by the fiber adapter at agent load; this tracker only reads them.
+ */
+import type { IdleTracker } from './tracker';
+
+export interface ReactWorkSource {
+  pendingRootWork(): string[];
+  pendingSchedulerTasks(): string[];
+}
+
+export class ReactTracker implements IdleTracker {
+  readonly name = 'react';
+
+  constructor(private readonly source: ReactWorkSource) {}
+
+  isIdle(): boolean {
+    return this.source.pendingRootWork().length === 0 && this.source.pendingSchedulerTasks().length === 0;
+  }
+
+  describeBusy(): string[] {
+    return [...this.source.pendingRootWork(), ...this.source.pendingSchedulerTasks()];
+  }
+
+  install(): void {}
+  uninstall(): void {}
+}

package/src/sync/timer.ts

@@ -0,0 +1,124 @@
+/**
+ * Pending timer tracker (requirements.md §6.2-2): counts `setTimeout` with delay ≤ threshold
+ * (default 1500ms). `setInterval` is only counted when `countIntervals` is set.
+ * The agent's own timers use `realClock` (captured before patching) and are never counted.
+ */
+import { SyncDefaults } from '@quiesco/protocol';
+
+import type { IdleTracker } from './tracker';
+import { isFunction, patch } from './tracker';
+
+type SetFn = (this: unknown, cb: unknown, ms?: number, ...args: unknown[]) => unknown;
+type ClearFn = (this: unknown, id: unknown) => void;
+
+export interface TimerGlobals {
+  setTimeout: SetFn;
+  clearTimeout: ClearFn;
+  setInterval?: SetFn;
+  clearInterval?: ClearFn;
+}
+
+export interface TimerTrackerOptions {
+  target?: TimerGlobals;
+  thresholdMs?: number;
+  countIntervals?: boolean;
+  now?: () => number;
+}
+
+interface PendingTimer {
+  kind: 'setTimeout' | 'setInterval';
+  delay: number;
+  since: number;
+  name: string;
+}
+
+export class TimerTracker implements IdleTracker {
+  readonly name = 'timer';
+  private readonly pending = new Map<unknown, PendingTimer>();
+  private readonly restores: (() => void)[] = [];
+  private readonly target: TimerGlobals;
+  private threshold: number;
+  private countIntervals: boolean;
+  private readonly now: () => number;
+
+  constructor(options: TimerTrackerOptions = {}) {
+    this.target = options.target ?? (globalThis as unknown as TimerGlobals);
+    this.threshold = options.thresholdMs ?? SyncDefaults.timerThresholdMs;
+    this.countIntervals = options.countIntervals ?? SyncDefaults.countIntervals;
+    this.now = options.now ?? Date.now;
+  }
+
+  /** Applies to timers created from now on. */
+  configure(options: { thresholdMs?: number; countIntervals?: boolean }): void {
+    if (options.thresholdMs !== undefined) this.threshold = options.thresholdMs;
+    if (options.countIntervals !== undefined) {
+      this.countIntervals = options.countIntervals;
+      if (!this.countIntervals) for (const [id, p] of this.pending) if (p.kind === 'setInterval') this.pending.delete(id);
+    }
+  }
+
+  isIdle(): boolean {
+    return this.pending.size === 0;
+  }
+
+  describeBusy(): string[] {
+    const t = this.now();
+    return [...this.pending.values()].map((p) => {
+      const left = p.kind === 'setTimeout' ? `, fires in ${Math.max(0, p.delay - (t - p.since))}ms` : '';
+      return `${p.kind}(${p.name}, ${p.delay}ms)${left}`;
+    });
+  }
+
+  install(): void {
+    if (this.restores.length > 0) return;
+    const self = this;
+    const t = this.target;
+    this.restores.push(
+      patch(t, 'setTimeout', (original) =>
+        function (this: unknown, cb: unknown, ms?: number, ...args: unknown[]) {
+          const delay = Number(ms ?? 0) || 0;
+          if (!isFunction(cb) || delay > self.threshold) return original.call(this, cb, ms, ...args);
+          const wrapped = function (this: unknown, ...a: unknown[]) {
+            self.pending.delete(id);
+            return (cb as (...x: unknown[]) => unknown).apply(this, a);
+          };
+          const id: unknown = original.call(this, wrapped, ms, ...args);
+          self.pending.set(id, { kind: 'setTimeout', delay, since: self.now(), name: cb.name || 'anonymous' });
+          return id;
+        },
+      ),
+      patch(t, 'clearTimeout', (original) =>
+        function (this: unknown, id: unknown) {
+          self.pending.delete(id);
+          return original.call(this, id);
+        },
+      ),
+    );
+    if (isFunction(t.setInterval) && isFunction(t.clearInterval)) {
+      const it = t as Required<TimerGlobals>;
+      this.restores.push(
+        patch(it, 'setInterval', (original) =>
+          function (this: unknown, cb: unknown, ms?: number, ...args: unknown[]) {
+            const delay = Number(ms ?? 0) || 0;
+            const id = original.call(this, cb, ms, ...args);
+            if (self.countIntervals && isFunction(cb) && delay <= self.threshold) {
+              self.pending.set(id, { kind: 'setInterval', delay, since: self.now(), name: cb.name || 'anonymous' });
+            }
+            return id;
+          },
+        ),
+        patch(it, 'clearInterval', (original) =>
+          function (this: unknown, id: unknown) {
+            self.pending.delete(id);
+            return original.call(this, id);
+          },
+        ),
+      );
+    }
+  }
+
+  uninstall(): void {
+    while (this.restores.length > 0) this.restores.pop()?.();
+    this.pending.clear();
+  }
+}

package/src/sync/tracker.ts

@@ -0,0 +1,51 @@
+/** Idle tracker contract (requirements.md §6.2). */
+export interface IdleTracker {
+  readonly name: string;
+  isIdle(): boolean;
+  /** Human-readable reasons, e.g. `GET https://api.example.com/todos (1200ms)`. Empty when idle. */
+  describeBusy(): string[];
+  install(): void;
+  uninstall(): void;
+  /** Optional: called when a waitForIdle starts / ends (frame-stable only samples while waiting). */
+  beginWait?(): void;
+  endWait?(): void;
+}
+
+/** Timer functions the agent uses for its own scheduling. They must NOT be the tracked ones. */
+export interface Clock {
+  setTimeout(cb: () => void, ms: number): unknown;
+  clearTimeout(id: unknown): void;
+  now(): number;
+}
+
+type AnyFn = (...args: never[]) => unknown;
+
+/** Replace `obj[key]` and return a function that restores it (only if nobody replaced it since). */
+export function patch<T extends object, K extends keyof T>(obj: T, key: K, make: (original: T[K]) => T[K]): () => void {
+  const original = obj[key];
+  const replacement = make(original);
+  obj[key] = replacement;
+  return () => {
+    if (obj[key] === replacement) obj[key] = original;
+  };
+}
+
+export function isFunction(v: unknown): v is AnyFn {
+  return typeof v === 'function';
+}
+
+/**
+ * Real timers captured when this module is first evaluated, i.e. before any tracker patches the
+ * globals (the agent is the first import of the app entry).
+ */
+const g = globalThis as unknown as {
+  setTimeout: (cb: () => void, ms: number) => unknown;
+  clearTimeout: (id: unknown) => void;
+};
+const realSetTimeout = g.setTimeout;
+const realClearTimeout = g.clearTimeout;
+export const realClock: Clock = {
+  setTimeout: (cb, ms) => realSetTimeout.call(globalThis, cb, ms),
+  clearTimeout: (id) => realClearTimeout.call(globalThis, id),
+  now: () => Date.now(),
+};

package/src/sync/wait-for-idle.ts

@@ -0,0 +1,141 @@
+/**
+ * waitForIdle (requirements.md §6.2): all enabled trackers idle in two consecutive checks that run
+ * in DIFFERENT macrotasks (docs/spikes/02-react-idle.md §4 — a single check misreports idle when a
+ * batch of expired timers runs without draining microtasks in between).
+ */
+import { SyncDefaults } from '@quiesco/protocol';
+import type { TrackerState } from '@quiesco/protocol';
+
+import { QuiescoError } from '../errors';
+import type { Clock, IdleTracker } from './tracker';
+import { realClock } from './tracker';
+
+export interface WaitForIdleOptions {
+  timeoutMs?: number;
+  /** Delay between checks while busy. The confirmation check always runs in the very next macrotask. */
+  pollIntervalMs?: number;
+  /**
+   * Timeout of the whole call this wait belongs to (an action waits with what is left of it), used in
+   * the SYNC_TIMEOUT message. Default: `timeoutMs`.
+   */
+  reportedTimeoutMs?: number;
+}
+
+const DEFAULT_POLL_MS = 16;
+const NO_NAMES: ReadonlySet<string> = new Set();
+
+export class SyncEngine {
+  private installed = false;
+  private disabled = new Set<string>();
+  /** Trackers that cannot settle right now (e.g. no frames while the app is in the background). */
+  private skipped: () => ReadonlySet<string> = () => NO_NAMES;
+  private inBackground: () => boolean = () => false;
+  private onBackgroundChange: ((wake: () => void) => () => void) | undefined;
+
+  constructor(
+    readonly trackers: readonly IdleTracker[],
+    private readonly clock: Clock = realClock,
+  ) {}
+
+  install(): void {
+    if (this.installed) return;
+    for (const t of this.trackers) t.install();
+    this.installed = true;
+  }
+
+  uninstall(): void {
+    if (!this.installed) return;
+    for (const t of this.trackers) t.uninstall();
+    this.installed = false;
+  }
+
+  /** Trackers listed as `false` are ignored by waitForIdle / getIdleState (they stay installed). */
+  setEnabled(enabled: Readonly<Record<string, boolean | undefined>>): void {
+    this.disabled = new Set(Object.entries(enabled).filter(([, on]) => on === false).map(([name]) => name));
+  }
+
+  /**
+   * Trackers named by `fn()` at check time count as idle (Phase 6.5: in the background Android pauses
+   * RN timers and no frames are drawn, so they would never settle).
+   */
+  setSkipped(fn: () => ReadonlySet<string>): void {
+    this.skipped = fn;
+  }
+
+  /**
+   * While `inBackground()`, Android pauses the JS timers (findings 6.7 batch C: a permission dialog is
+   * another activity), so a wait sleeping on a timer would neither end nor time out. `onChange` wakes it
+   * (AppState events still arrive), and in the background it returns as soon as every active tracker is
+   * idle, without the confirmation check in a later macrotask (that needs a timer; nothing runs anyway).
+   */
+  setBackground(inBackground: () => boolean, onChange?: (wake: () => void) => () => void): void {
+    this.inBackground = inBackground;
+    this.onBackgroundChange = onChange;
+  }
+
+  private active(): IdleTracker[] {
+    const skipped = safe(() => this.skipped(), NO_NAMES);
+    return this.trackers.filter((t) => !this.disabled.has(t.name) && !skipped.has(t.name));
+  }
+
+  getIdleState(): TrackerState[] {
+    return this.active().map((t) => {
+      const idle = safe(() => t.isIdle(), false);
+      return { name: t.name, idle, busy: idle ? [] : safe(() => t.describeBusy(), ['describeBusy() threw']) };
+    });
+  }
+
+  async waitForIdle(options: WaitForIdleOptions = {}): Promise<{ waitedMs: number }> {
+    const timeoutMs = options.timeoutMs ?? SyncDefaults.timeoutMs;
+    const pollMs = options.pollIntervalMs ?? DEFAULT_POLL_MS;
+    const start = this.clock.now();
+    const trackers = this.active();
+    let wake: (() => void) | null = null;
+    const unsubscribe = safe(() => this.onBackgroundChange?.(() => wake?.()), undefined);
+    const sleep = (ms: number) =>
+      new Promise<void>((resolve) => {
+        wake = resolve;
+        this.clock.setTimeout(resolve, ms);
+      });
+    for (const t of trackers) t.beginWait?.();
+    try {
+      for (;;) {
+        if (this.allIdle()) {
+          if (safe(() => this.inBackground(), false)) return { waitedMs: this.clock.now() - start };
+          await sleep(0);
+          if (this.allIdle()) return { waitedMs: this.clock.now() - start };
+        }
+        const elapsed = this.clock.now() - start;
+        if (elapsed >= timeoutMs) throw this.timeoutError(options.reportedTimeoutMs ?? timeoutMs, elapsed);
+        await sleep(Math.min(pollMs, timeoutMs - elapsed));
+      }
+    } finally {
+      wake = null;
+      safe(() => unsubscribe?.(), undefined);
+      for (const t of trackers) t.endWait?.();
+    }
+  }
+
+  private allIdle(): boolean {
+    return this.active().every((t) => safe(() => t.isIdle(), false));
+  }
+
+  private timeoutError(timeoutMs: number, waitedMs: number): QuiescoError<'SYNC_TIMEOUT'> {
+    const busy = this.getIdleState().filter((s) => !s.idle);
+    const lines = busy.map((s) => `  - ${s.name}: ${s.busy.length > 0 ? s.busy.join('; ') : 'busy'}`);
+    const waited = waitedMs < timeoutMs ? ` (waited ${waitedMs}ms for idle after the action)` : '';
+    return new QuiescoError('SYNC_TIMEOUT', `App did not become idle within the ${timeoutMs}ms timeout${waited}. Busy:\n${lines.join('\n')}`, {
+      timeoutMs,
+      busy,
+    });
+  }
+
+}
+
+function safe<T>(fn: () => T, fallback: T): T {
+  try {
+    return fn();
+  } catch {
+    return fallback;
+  }
+}

package/src/version.ts

@@ -0,0 +1,2 @@
+/** Reported in `hello`. Keep in sync with package.json (checked by a unit test). */
+export const AGENT_VERSION = '0.1.0';