Make your computer a home for your AI partner. Avibe is the local-first Agent OS: Vibey, its built-in AI partner, works out of the box, and Claude Code, Codex & OpenCode run unchanged beside it — reach them from your browser, phone, or any chat app.
Python agentagent-osaiai-agentsai-partnerchatopsclaudeclaude-codecodexdevtoolsdiscord-botlark-botllmlocal-firstlong-term-memoryopencodeslack-botvibe-codingvibeywechat
// @vitest-environment jsdom
import { useEffect, useLayoutEffect } from 'react';
import { act, cleanup, renderHook } from '@testing-library/react';
import { createRoot } from 'react-dom/client';
import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
import { resetCoalescedWrites, useCoalescedWrite } from './useCoalescedWrite';
type Deferred = {
promise: Promise<boolean>;
resolve: (value: boolean) => void;
reject: (reason: unknown) => void;
};
function deferred(): Deferred {
let resolve!: (value: boolean) => void;
let reject!: (reason: unknown) => void;
const promise = new Promise<boolean>((onResolve, onReject) => {
resolve = onResolve;
reject = onReject;
});
return { promise, resolve, reject };
}
function settle() {
return act(async () => {
await Promise.resolve();
await Promise.resolve();
});
}
// Records what reached the network as `<key>:<patch>` and hands back a gate per
// call, so a write can be observed as "not sent yet" rather than merely "not
// resolved yet".
function gatedSend(started: string[], pending: Map<string, Deferred>) {
return vi.fn(async (patch: string, key: string) => {
const label = `${key}:${patch}`;
started.push(label);
const gate = deferred();
pending.set(label, gate);
return gate.promise;
});
}
// Merges string patches as `a+b`, standing in for the session row's field union.
const joinMerge = (prev: string, next: string) => `${prev}+${next}`;
describe('useCoalescedWrite', () => {
// The store is module state on purpose (it outlives the component); each case
// starts from an empty one.
beforeEach(resetCoalescedWrites);
afterEach(cleanup);
it('keeps one request per resource in flight and folds the clicks made during it into one follow-up', async () => {
const started: string[] = [];
const pending = new Map<string, Deferred>();
const send = gatedSend(started, pending);
const { result } = renderHook(() => useCoalescedWrite<string>('t', send, { merge: joinMerge }));
act(() => {
result.current.write('s1', 'first');
result.current.write('s1', 'second');
result.current.write('s1', 'third');
});
await settle();
// Nothing about the later clicks may reach the network while the first
// request is still deciding what the server holds.
expect(started).toEqual(['s1:first']);
await act(async () => {
pending.get('s1:first')!.resolve(true);
await pending.get('s1:first')!.promise;
});
await settle();
// Two clicks, one follow-up request: the intermediate state was transit.
expect(started).toEqual(['s1:first', 's1:second+third']);
});
it('does not make one resource wait behind another', async () => {
const started: string[] = [];
const pending = new Map<string, Deferred>();
const send = gatedSend(started, pending);
const { result } = renderHook(() => useCoalescedWrite<string>('t', send));
act(() => {
result.current.write('s1', 'a');
result.current.write('s2', 'b');
});
await settle();
expect(started).toEqual(['s1:a', 's2:b']);
expect(result.current.isSaving('s1')).toBe(true);
expect(result.current.isSaving('s2')).toBe(true);
});
it('does not let two owners of the same resource race after a remount', async () => {
const started: string[] = [];
const pending = new Map<string, Deferred>();
const send = gatedSend(started, pending);
const first = renderHook(() => useCoalescedWrite<string>('t', send, { merge: joinMerge }));
act(() => {
first.result.current.write('s1', 'from-first-mount');
});
await settle();
expect(started).toEqual(['s1:from-first-mount']);
// The user navigates away mid-request and comes back: a hook-local queue
// would start a second request beside the first and let the older one commit
// last.
first.unmount();
const second = renderHook(() => useCoalescedWrite<string>('t', send, { merge: joinMerge }));
expect(second.result.current.isSaving('s1')).toBe(true);
act(() => {
second.result.current.write('s1', 'from-second-mount');
});
await settle();
expect(started).toEqual(['s1:from-first-mount']);
await act(async () => {
pending.get('s1:from-first-mount')!.resolve(true);
await pending.get('s1:from-first-mount')!.promise;
});
await settle();
expect(started).toEqual(['s1:from-first-mount', 's1:from-second-mount']);
second.unmount();
});
it('hands the burst to the owner that is on screen when it settles', async () => {
const started: string[] = [];
const pending = new Map<string, Deferred>();
const send = gatedSend(started, pending);
const settled: string[] = [];
const mount = (tag: string) =>
renderHook(() =>
useCoalescedWrite<string>('t', send, {
onSettled: (key, committed) => {
settled.push(`${tag}:${key}:${committed}`);
},
}),
);
const first = mount('gone');
act(() => {
first.result.current.write('s1', 'route');
});
await settle();
first.unmount();
const second = mount('live');
await settle();
await act(async () => {
pending.get('s1:route')!.resolve(true);
await pending.get('s1:route')!.promise;
});
await settle();
// The answer lands on the screen that is there when it arrives. Reconciling
// into the unmounted page would leave the live one showing an optimistic
// route nobody ever converged — and no `setState` there could fix it.
expect(settled).toEqual(['live:s1:true']);
// Handing the burst over is not a reason to re-send it.
expect(started).toEqual(['s1:route']);
expect(second.result.current.isSaving('s1')).toBe(false);
second.unmount();
});
it('claims the scope in the commit, so an answer landing before passive effects still finds the live owner', async () => {
const started: string[] = [];
const pending = new Map<string, Deferred>();
const send = gatedSend(started, pending);
const settled: string[] = [];
// Whether the replacement page's own passive effects had run by the time the
// answer was handled — recorded WITH the settlement, so a React that stopped
// leaving this window open fails the case instead of passing it vacuously.
let passiveEffectsRan = false;
const record = (tag: string) => (key: string, committed: boolean) => {
settled.push(`${tag}:${key}:${committed}:${passiveEffectsRan ? 'late' : 'in-window'}`);
};
const Live = () => {
useCoalescedWrite<string>('t', send, { onSettled: record('live') });
// Answers the request from inside the commit that puts this page on screen.
// Both markers are declared AFTER the hook, so each runs behind whatever the
// hook registered in its own phase.
useLayoutEffect(() => {
pending.get('s1:route')!.resolve(true);
}, []);
useEffect(() => {
passiveEffectsRan = true;
}, []);
return null;
};
const gone = renderHook(() => useCoalescedWrite<string>('t', send, { onSettled: record('gone') }));
act(() => {
gone.result.current.write('s1', 'route');
});
await settle();
gone.unmount();
// React runs passive effects in a LATER task than the commit, so a
// replacement page is on screen for a while with none of them run yet. `act`
// and `flushSync` both close that window by flushing them before they return,
// and this case is about what happens inside it — so it drives React directly.
const container = document.createElement('div');
document.body.appendChild(container);
const root = createRoot(container);
const actEnvironment = globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean };
const wasActEnvironment = actEnvironment.IS_REACT_ACT_ENVIRONMENT;
actEnvironment.IS_REACT_ACT_ENVIRONMENT = false;
try {
root.render(<Live />);
// Let the scheduler commit the mount, hand the answer to whoever owns the
// scope by then, and finally run the queued passive effects.
while (!settled.length) await new Promise((r) => setTimeout(r, 0));
// Being rendered is what makes a page the live owner. Answering into the
// page it replaced releases the optimistic overlay through a dead component
// — the row the user is looking at keeps whatever it was showing, and no
// settlement is left to converge it.
expect(settled).toEqual(['live:s1:true:in-window']);
expect(started).toEqual(['s1:route']);
} finally {
actEnvironment.IS_REACT_ACT_ENVIRONMENT = wasActEnvironment;
await act(async () => {
root.unmount();
});
container.remove();
}
});
it('reports which write opened the burst', async () => {
const started: string[] = [];
const pending = new Map<string, Deferred>();
const send = gatedSend(started, pending);
const opened: boolean[] = [];
const { result } = renderHook(() => useCoalescedWrite<string>('t', send, { merge: joinMerge }));
act(() => {
opened.push(result.current.write('s1', 'a'));
opened.push(result.current.write('s1', 'b'));
opened.push(result.current.write('s2', 'c'));
});
await settle();
// The opening write is the one moment at which the state the burst replaces
// is still what the owner holds, so an owner that must revert a rejected
// burst captures its base here and accumulates into it afterwards. Per
// resource, not per click: `s2` opens its own burst.
expect(opened).toEqual([true, false, true]);
await act(async () => {
pending.get('s2:c')!.resolve(true);
await pending.get('s2:c')!.promise;
});
await settle();
act(() => {
opened.push(result.current.write('s2', 'd'));
});
await settle();
// Settled means the base is spent: the next click opens a fresh burst and
// captures the state the server confirmed.
expect(opened).toEqual([true, false, true, true]);
});
it('drops what is waiting when the request in flight fails', async () => {
const started: string[] = [];
const pending = new Map<string, Deferred>();
const send = gatedSend(started, pending);
const settled: Array<[string, boolean]> = [];
const { result } = renderHook(() =>
useCoalescedWrite<string>('t', send, {
merge: joinMerge,
onSettled: (key, committed) => {
settled.push([key, committed]);
},
}),
);
act(() => {
result.current.write('s1', 'title');
});
await settle();
act(() => {
result.current.write('s1', 'route');
});
// The write in flight is rejected. What was clicked behind it was composed
// against the state that request was installing — the state the server has
// just refused — so sending it now would persist a combination nobody picked.
// This owner declares no `standsAlone`, which is the conservative default: the
// failure ends the burst, and the owner's reconcile takes the whole burst back.
await act(async () => {
pending.get('s1:title')!.resolve(false);
await Promise.resolve();
});
await settle();
expect(started).toEqual(['s1:title']);
// One settle per burst, reporting the burst's outcome.
expect(settled).toEqual([['s1', false]]);
expect(result.current.isSaving('s1')).toBe(false);
});
// A payload that carries its whole resource was composed against nothing, so a
// refusal says nothing about it: it is the user's newest intent and still
// coherent. Dropping it would lose a click to protect against a mismatch that
// cannot happen — while the burst's shape is unchanged, because `committed`
// already means "the outcome of the last send".
const standsAloneWhenWhole = (patch: string) => patch.startsWith('whole');
it('sends what is waiting past a failure when that patch stands on its own', async () => {
const started: string[] = [];
const pending = new Map<string, Deferred>();
const send = gatedSend(started, pending);
const settled: Array<[string, boolean]> = [];
const { result } = renderHook(() =>
useCoalescedWrite<string>('t', send, {
merge: joinMerge,
standsAlone: standsAloneWhenWhole,
onSettled: (key, committed) => {
settled.push([key, committed]);
},
}),
);
act(() => {
result.current.write('s1', 'partial');
});
await settle();
act(() => {
result.current.write('s1', 'whole');
});
await act(async () => {
pending.get('s1:partial')!.resolve(false);
await Promise.resolve();
});
await settle();
// Sent, not dropped — and nothing has settled yet, because the burst is still
// going: the resource is still mid-write.
expect(started).toEqual(['s1:partial', 's1:whole']);
expect(settled).toEqual([]);
expect(result.current.isSaving('s1')).toBe(true);
await act(async () => {
pending.get('s1:whole')!.resolve(true);
await Promise.resolve();
});
await settle();
// One settle for the burst, reporting the send that ended it: the server holds
// the user's newest pick, so the owner converges instead of reverting.
expect(settled).toEqual([['s1', true]]);
expect(result.current.isSaving('s1')).toBe(false);
});
it('ends the burst as refused when the patch that stood alone is refused too', async () => {
const started: string[] = [];
const pending = new Map<string, Deferred>();
const send = gatedSend(started, pending);
const settled: Array<[string, boolean]> = [];
const { result } = renderHook(() =>
useCoalescedWrite<string>('t', send, {
merge: joinMerge,
standsAlone: standsAloneWhenWhole,
onSettled: (key, committed) => {
settled.push([key, committed]);
},
}),
);
act(() => {
result.current.write('s1', 'whole-a');
});
await settle();
act(() => {
result.current.write('s1', 'whole-b');
});
await act(async () => {
pending.get('s1:whole-a')!.resolve(false);
await Promise.resolve();
});
await settle();
await act(async () => {
pending.get('s1:whole-b')!.resolve(false);
await Promise.resolve();
});
await settle();
expect(started).toEqual(['s1:whole-a', 's1:whole-b']);
// Still ONE settle for the burst, still reporting the last send — continuing
// past a failure must not turn one burst into two reconciles, or the owner
// would revert, re-read, and revert again.
expect(settled).toEqual([['s1', false]]);
expect(result.current.isSaving('s1')).toBe(false);
});
it('asks with both payloads, so the same pending patch can be answered either way', async () => {
const started: string[] = [];
const pending = new Map<string, Deferred>();
const send = gatedSend(started, pending);
const asked: Array<[string, string]> = [];
// The identical pending payload, behind two different refusals: whether it
// stands alone is a property of the PAIR, so an owner that is told only what
// waits cannot answer at all.
const standsAlone = (patch: string, refused: string) => {
asked.push([patch, refused]);
return refused === 'same-field';
};
const { result } = renderHook(() => useCoalescedWrite<string>('t', send, { merge: joinMerge, standsAlone }));
act(() => {
result.current.write('s1', 'same-field');
result.current.write('s2', 'wider');
});
await settle();
act(() => {
result.current.write('s1', 'b');
result.current.write('s2', 'b');
});
await act(async () => {
pending.get('s1:same-field')!.resolve(false);
pending.get('s2:wider')!.resolve(false);
await Promise.resolve();
});
await settle();
expect(asked).toEqual([
['b', 'same-field'],
['b', 'wider'],
]);
expect(started).toEqual(['s1:same-field', 's2:wider', 's1:b']);
});
it('asks about the MOST RECENT send, so a burst that fails twice compares against the right one', async () => {
const started: string[] = [];
const pending = new Map<string, Deferred>();
const send = gatedSend(started, pending);
const asked: Array<[string, string]> = [];
const standsAlone = (patch: string, refused: string) => {
asked.push([patch, refused]);
return true;
};
const { result } = renderHook(() => useCoalescedWrite<string>('t', send, { merge: joinMerge, standsAlone }));
act(() => {
result.current.write('s1', 'a');
});
await settle();
act(() => {
result.current.write('s1', 'b');
});
await act(async () => {
pending.get('s1:a')!.resolve(false);
await Promise.resolve();
});
await settle();
act(() => {
result.current.write('s1', 'c');
});
await act(async () => {
pending.get('s1:b')!.resolve(false);
await Promise.resolve();
});
await settle();
// ``c`` is weighed against ``b``, never against ``a``: the first failure is
// already accounted for by the payload the second one sent, and comparing
// against a patch two sends back would answer a question nobody asked.
expect(asked).toEqual([
['b', 'a'],
['c', 'b'],
]);
expect(started).toEqual(['s1:a', 's1:b', 's1:c']);
});
it('treats a throw as a failed write', async () => {
const started: string[] = [];
const boom = deferred();
const send = vi.fn(async (patch: string, key: string) => {
started.push(`${key}:${patch}`);
if (patch === 'boom') return boom.promise;
return true;
});
const settled: Array<[string, boolean]> = [];
const { result } = renderHook(() =>
useCoalescedWrite<string>('t', send, {
onSettled: (key, committed) => {
settled.push([key, committed]);
},
}),
);
act(() => {
result.current.write('s1', 'boom');
});
await settle();
act(() => {
result.current.write('s1', 'after');
});
await act(async () => {
boom.reject(new Error('network'));
await boom.promise.catch(() => undefined);
});
await settle();
// A throw counts as a failure, so it ends the burst the same way a `false`
// does — including the patch that was waiting behind it.
expect(started).toEqual(['s1:boom']);
expect(settled).toEqual([['s1', false]]);
expect(result.current.isSaving('s1')).toBe(false);
});
it('reports a burst that committed in parts as uncommitted, leaving the extent to the owner', async () => {
const started: string[] = [];
const pending = new Map<string, Deferred>();
const send = gatedSend(started, pending);
const settled: Array<[string, boolean]> = [];
const { result } = renderHook(() =>
useCoalescedWrite<string>('t', send, {
merge: joinMerge,
onSettled: (key, committed) => {
settled.push([key, committed]);
},
}),
);
act(() => {
result.current.write('s1', 'agent');
});
await settle();
act(() => {
result.current.write('s1', 'effort');
});
await act(async () => {
pending.get('s1:agent')!.resolve(true);
await pending.get('s1:agent')!.promise;
});
await settle();
expect(started).toEqual(['s1:agent', 's1:effort']);
await act(async () => {
pending.get('s1:effort')!.resolve(false);
await pending.get('s1:effort')!.promise;
});
await settle();
// A burst can commit in PARTS: the first request landed, the patch folded in
// behind it was refused. There is still ONE settle, and `committed` reports
// the burst's outcome — false, because the state the owner is showing is not
// the state the server holds.
//
// What it deliberately does NOT say is how much of the burst survived. The
// writer never sees the payloads' fields (they are the owner's shape, merged
// by the owner's `merge`), so only the owner can know that the Agent pick is
// on the server and the effort pick is not. An owner that reverts to where its
// burst STARTED would undo the committed part; the owners here advance their
// rollback target on each successful send instead.
expect(settled).toEqual([['s1', false]]);
expect(result.current.isSaving('s1')).toBe(false);
});
it('stays mid-write until the reconcile finishes and folds a pick made during it into the same writer', async () => {
const started: string[] = [];
const pending = new Map<string, Deferred>();
const send = gatedSend(started, pending);
const reconcile = deferred();
const { result } = renderHook(() =>
useCoalescedWrite<string>('t', send, {
onSettled: () => reconcile.promise.then(() => undefined),
}),
);
act(() => {
result.current.write('p1', 'route');
});
await settle();
await act(async () => {
pending.get('p1:route')!.resolve(true);
await Promise.resolve();
});
await settle();
// The authoritative re-read is in flight: the project is still mid-write, so
// the picker keeps its indicator and nothing starts a fresh burst against
// state the read is still rewriting.
expect(result.current.isSaving('p1')).toBe(true);
act(() => {
result.current.write('p1', 'next');
});
await settle();
expect(started).toEqual(['p1:route']);
await act(async () => {
reconcile.resolve(true);
await reconcile.promise;
});
await settle();
// A pick made during a SUCCESSFUL burst's reconcile is still live intent: it
// was composed against a route the server took, so it goes out.
expect(started).toEqual(['p1:route', 'p1:next']);
expect(result.current.isSaving('p1')).toBe(true);
await act(async () => {
pending.get('p1:next')!.resolve(true);
await pending.get('p1:next')!.promise;
});
await settle();
expect(result.current.isSaving('p1')).toBe(false);
});
it('drops a pick made while a failed burst is rolling back', async () => {
const started: string[] = [];
const pending = new Map<string, Deferred>();
const send = gatedSend(started, pending);
const rollback = deferred();
const { result } = renderHook(() =>
useCoalescedWrite<string>('t', send, {
onSettled: () => rollback.promise.then(() => undefined),
}),
);
act(() => {
result.current.write('p1', 'route');
});
await settle();
await act(async () => {
pending.get('p1:route')!.resolve(false);
await Promise.resolve();
});
await settle();
// The rollback read is in flight, so the row on screen is still the one the
// server refused.
expect(result.current.isSaving('p1')).toBe(true);
act(() => {
result.current.write('p1', 'during-rollback');
});
await act(async () => {
rollback.resolve(true);
await rollback.promise;
});
await settle();
// This pick was composed against the refused row, so it goes back with it.
// The rollback lands whole and the user picks again from what the server
// actually holds.
expect(started).toEqual(['p1:route']);
expect(result.current.isSaving('p1')).toBe(false);
});
it('keeps two scopes writing the same id apart', async () => {
const started: string[] = [];
const pending = new Map<string, Deferred>();
const send = gatedSend(started, pending);
const rows = renderHook(() => useCoalescedWrite<string>('rows', send));
const routes = renderHook(() => useCoalescedWrite<string>('routes', send));
act(() => {
rows.result.current.write('x', 'row');
routes.result.current.write('x', 'route');
});
await settle();
expect(started).toEqual(['x:row', 'x:route']);
expect(rows.result.current.isSaving('x')).toBe(true);
expect(routes.result.current.isSaving('x')).toBe(true);
await act(async () => {
pending.get('x:row')!.resolve(true);
await pending.get('x:row')!.promise;
});
await settle();
expect(rows.result.current.isSaving('x')).toBe(false);
expect(routes.result.current.isSaving('x')).toBe(true);
});
it('uses the newest send closure', async () => {
const calls: string[] = [];
const { result, rerender } = renderHook(
({ tag }: { tag: string }) =>
useCoalescedWrite<string>('t', async (patch: string) => {
calls.push(`${tag}:${patch}`);
return true;
}),
{ initialProps: { tag: 'first' } },
);
rerender({ tag: 'second' });
act(() => {
result.current.write('s1', 'a');
});
await settle();
expect(calls).toEqual(['second:a']);
});
});