mirror of
https://github.com/getpaseo/paseo.git
synced 2026-11-08 09:24:41 +00:00
Mohamed Boudra
f539ccf1c0
* fix(client): recover a dead connection within seconds of returning to the foreground A socket that died while the OS had JS suspended stays OPEN and keeps accepting sends, so nothing but inbound frames can prove it alive. Since #8651 the foreground check rode the regular heartbeat: a 15 s window, dedupe onto a probe that straddled the suspension, misses from before background carried over, and a 1.5 s backoff after teardown. Measured at the transport: 40 s to tear down and 41.5 s to reconnect, with 15 s to 30 s variations depending on what was in flight when the app was suspended. Foreground now starts a fresh cycle inside the same heartbeat owner: two 5 s windows back to back, then teardown and an immediate reconnect. An outstanding heartbeat probe is dropped without a miss because it measured the suspension, not the socket; a latency measurement keeps its own deadline and is shared. Repeated foreground events join the running cycle instead of restarting it. The rule that any validated inbound frame voids a window is unchanged, so a slow multi-frame transfer still survives, and after any progress the heartbeat returns to its 10 s / 15 s cadence. Ordinary heartbeat teardowns keep their backoff; only the foreground cycle reconnects at once, and a failed immediate attempt backs off as before. A single frame that takes longer than the two windows to arrive after foreground is still torn down. That needs smaller daemon-to-client frames and is documented as a known limit. * fix(client): count only fresh evidence in the foreground liveness cycle Two gaps in the foreground cycle let stale evidence decide a fresh check. A latency measurement outstanding at foreground is shared by the check. If a frame had arrived during that measurement before the app was suspended, the check read that old activity as "alive" and went back to the normal cadence without running its windows. The check now clears the shared probe's activity flag when it begins, so only frames that arrive from then on count. If the app was suspended again inside the second window, the next resume either found the queued expiry already fired (teardown before AppState) or deduped onto the old probe and let the expiry fire right after (teardown with no fresh window). A foreground window whose timer fires well past its deadline on the wall clock spanned a suspension; it is now discarded together with any activity it saw and the misses before it, and the cycle starts over. The wall clock is used because the monotonic clock may not advance while the OS has the process suspended. * fix(client): keep latency measurements alive when foreground replaces a heartbeat A latency measurement that found a heartbeat ping outstanding joins that probe. The foreground check used to fail the probe outright to start its fresh window, which rejected the measurement before its own deadline on a healthy socket; the diagnostics collector treats that as a failed collection. The superseded probe is now detached without settling and takes the outcome of the fresh window, so the heartbeat tick and any measurement waiting on it see the next pong or the window's timeout instead of a spurious error. * fix(client): let latency measurements wait for the next pong instead of a probe A measurement that joined an outstanding heartbeat probe took that probe's fate. The foreground check replaces such a probe, so the measurement failed early: first with the supersede error, then, after the hand-off to the fresh window, with that window's five-second timeout even when the caller had asked for a longer deadline and the pong was about to arrive. Measurements now register as pong waiters. A waiter settles on the next pong, on a connection failure (close, transport dispose, ping send failure) or on its own deadline, and no longer cares which probe put the ping on the wire. The foreground check goes back to dropping the straddling heartbeat probe outright, since the only thing waiting on a probe's promise is the heartbeat tick. * fix(client): report the joined ping's round trip from a latency measurement A measurement that joins an in-flight heartbeat ping used to start its clock at the join, so it reported only the remaining wait for the pong. The clock now starts at the send of the ping the measurement waits on, which matches what the heartbeat records for the same pong.
@getpaseo/client
TypeScript SDK for building integrations on top of a Paseo daemon.
npm install @getpaseo/client
import { createPaseoClient } from "@getpaseo/client";
const client = createPaseoClient({ url: "ws://127.0.0.1:6767/ws" });
await client.connect();
const agent = await client.agents.create({
config: { provider: "codex/gpt-5.5" },
cwd: "/Users/me/dev/storefront",
prompt: "Review the current diff and name the riskiest change.",
});
const result = await agent.waitForFinish();
console.log(result.lastMessage);
await client.close();
The public API is the package root. Imports under @getpaseo/client/internal/* are unsupported implementation details used by Paseo's own packages.
Read the SDK documentation for agents, workspaces, terminals, provider discovery, events, recipes, and the API reference. Runnable TypeScript patterns also live in examples/.
Runtime
The client needs a WebSocket implementation. Modern browsers and Node.js 22 provide one globally.
Use a WebSocket URL ending in /ws, such as ws://127.0.0.1:6767/ws. Pass password when the daemon requires authentication.
The client advertises its supported protocol capabilities by default. Optional capabilities
overrides extend or override that declaration; browser hosting must be supplied by the caller.
Connecting alone does not subscribe to agent timelines or catalog events. See the
event guide for subscription lifetimes and timeline replacements.
Stability
The high-level API exported from @getpaseo/client is the supported SDK surface. The SDK and daemon remain protocol-compatible across versions, but newly added capabilities can require a newer daemon.