run402 4.20.0 → 4.22.0

package/sdk/dist/wait.d.ts

@@ -0,0 +1,44 @@
+/**
+ * `waitFor` — the one poll loop (attention-architecture Wave E).
+ *
+ * Every wait on this platform is the same shape: fetch a fact, ask whether it
+ * has reached the state you need, sleep, repeat, stop at a deadline. Before
+ * this helper the shape was hand-rolled three times (escalations'
+ * `raiseAndWait`, the CLI's `--wait`, room catch-up polling), and each copy
+ * had to re-decide the one contract that matters:
+ *
+ * **Silence is an answer.** On timeout, `waitFor` RETURNS the last observed
+ * state — it never throws. A thrown timeout invites `catch`-and-proceed,
+ * which quietly converts "nobody answered" into consent. Returning the
+ * still-unsettled state forces the caller to look at it and decide, with
+ * "nothing happened" as a visible input rather than an exception it
+ * swallowed. (This is the same reason an exhausted escalation rests OPEN and
+ * a deploy gate must not auto-approve on timeout.)
+ */
+export interface WaitForOptions {
+    /** Delay between polls. Clamped to ≥1s so a tight loop cannot hammer the API. */
+    pollMs?: number;
+    /** Total budget. When it elapses, the LAST OBSERVED state is returned. */
+    timeoutMs?: number;
+    /**
+     * Called after each poll with the latest state — progress reporting
+     * (a CLI prints to stderr here) without owning the loop.
+     */
+    onPoll?: (state: unknown, elapsedMs: number) => void;
+}
+export interface WaitForResult<T> {
+    state: T;
+    /** True when `predicate` accepted `state`; false means the wait timed out. */
+    settled: boolean;
+    elapsedMs: number;
+    polls: number;
+}
+/**
+ * Poll `fetch` until `predicate(state)` is true or the timeout elapses.
+ *
+ * The initial state is fetched immediately (a wait that starts already
+ * settled costs one call and zero sleeps). A `fetch` rejection propagates —
+ * an API failure is not silence and must not be mistaken for it.
+ */
+export declare function waitFor<T>(fetchState: () => Promise<T>, predicate: (state: T) => boolean, opts?: WaitForOptions): Promise<WaitForResult<T>>;
+//# sourceMappingURL=wait.d.ts.map

package/sdk/dist/wait.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wait.d.ts","sourceRoot":"","sources":["../src/wait.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,MAAM,WAAW,cAAc;IAC7B,iFAAiF;IACjF,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,0EAA0E;IAC1E,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;OAGG;IACH,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,KAAK,IAAI,CAAC;CACtD;AAED,MAAM,WAAW,aAAa,CAAC,CAAC;IAC9B,KAAK,EAAE,CAAC,CAAC;IACT,8EAA8E;IAC9E,OAAO,EAAE,OAAO,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;;;;GAMG;AACH,wBAAsB,OAAO,CAAC,CAAC,EAC7B,UAAU,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EAC5B,SAAS,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,OAAO,EAChC,IAAI,GAAE,cAAmB,GACxB,OAAO,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,CAsB3B"}

package/sdk/dist/wait.js

@@ -0,0 +1,45 @@
+/**
+ * `waitFor` — the one poll loop (attention-architecture Wave E).
+ *
+ * Every wait on this platform is the same shape: fetch a fact, ask whether it
+ * has reached the state you need, sleep, repeat, stop at a deadline. Before
+ * this helper the shape was hand-rolled three times (escalations'
+ * `raiseAndWait`, the CLI's `--wait`, room catch-up polling), and each copy
+ * had to re-decide the one contract that matters:
+ *
+ * **Silence is an answer.** On timeout, `waitFor` RETURNS the last observed
+ * state — it never throws. A thrown timeout invites `catch`-and-proceed,
+ * which quietly converts "nobody answered" into consent. Returning the
+ * still-unsettled state forces the caller to look at it and decide, with
+ * "nothing happened" as a visible input rather than an exception it
+ * swallowed. (This is the same reason an exhausted escalation rests OPEN and
+ * a deploy gate must not auto-approve on timeout.)
+ */
+/**
+ * Poll `fetch` until `predicate(state)` is true or the timeout elapses.
+ *
+ * The initial state is fetched immediately (a wait that starts already
+ * settled costs one call and zero sleeps). A `fetch` rejection propagates —
+ * an API failure is not silence and must not be mistaken for it.
+ */
+export async function waitFor(fetchState, predicate, opts = {}) {
+    const pollMs = Math.max(opts.pollMs ?? 30_000, 1_000);
+    const timeoutMs = opts.timeoutMs ?? 60 * 60 * 1000;
+    const startedAt = Date.now();
+    let polls = 1;
+    let state = await fetchState();
+    opts.onPoll?.(state, Date.now() - startedAt);
+    while (!predicate(state) && Date.now() - startedAt + pollMs <= timeoutMs) {
+        await new Promise((resolve) => setTimeout(resolve, pollMs));
+        polls++;
+        state = await fetchState();
+        opts.onPoll?.(state, Date.now() - startedAt);
+    }
+    return {
+        state,
+        settled: predicate(state),
+        elapsedMs: Date.now() - startedAt,
+        polls,
+    };
+}
+//# sourceMappingURL=wait.js.map

package/sdk/dist/wait.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"wait.js","sourceRoot":"","sources":["../src/wait.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAsBH;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,OAAO,CAC3B,UAA4B,EAC5B,SAAgC,EAChC,OAAuB,EAAE;IAEzB,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,MAAM,IAAI,MAAM,EAAE,KAAK,CAAC,CAAC;IACtD,MAAM,SAAS,GAAG,IAAI,CAAC,SAAS,IAAI,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;IACnD,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IAE7B,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,IAAI,KAAK,GAAG,MAAM,UAAU,EAAE,CAAC;IAC/B,IAAI,CAAC,MAAM,EAAE,CAAC,KAAK,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS,CAAC,CAAC;IAE7C,OAAO,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS,GAAG,MAAM,IAAI,SAAS,EAAE,CAAC;QACzE,MAAM,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC,CAAC;QAC5D,KAAK,EAAE,CAAC;QACR,KAAK,GAAG,MAAM,UAAU,EAAE,CAAC;QAC3B,IAAI,CAAC,MAAM,EAAE,CAAC,KAAK,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS,CAAC,CAAC;IAC/C,CAAC;IAED,OAAO;QACL,KAAK;QACL,OAAO,EAAE,SAAS,CAAC,KAAK,CAAC;QACzB,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS;QACjC,KAAK;KACN,CAAC;AACJ,CAAC"}