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
// Async ownership rules extracted from the Models components so interleavings can
// be exercised directly: which request may land, what speaks for a row when no
// read does, how long a write counts as outstanding, when a drawer re-seeds, and
// whether a connect-flow transition may change an already terminal view.
import type { AgentMenu, AgentSupply, OAuthFlow, OAuthFlowState } from './types';
// ── Latest async result ────────────────────────────────────────────────────
/**
* Owns request ordering and the only path that may land a result. Callers start
* reads; they never reconstruct whether a response is still current.
*/
export const createLatestAsyncAuthority = <T>(land: (value: T) => void) => {
let latestRequest = 0;
return {
run: async (read: () => Promise<T>): Promise<'landed' | 'stale'> => {
const request = ++latestRequest;
try {
const value = await read();
if (request !== latestRequest) return 'stale';
land(value);
return 'landed';
} catch (error) {
if (request !== latestRequest) return 'stale';
throw error;
}
},
};
};
/**
* Orders reads at the granularity of the keys they install. A read claims the
* keys it will write before it starts, and when it returns it still owns every
* claimed key that no newer read has claimed since.
*
* Ownership is per key rather than per read so that two reads covering
* different keys never supersede each other, and a read that loses part of its
* claim still installs — and still answers for — the rest.
*/
export const createLatestAsyncAuthorityByKeySet = <K, T>(
land: (value: T, owned: ReadonlySet<K>) => void,
) => {
const latestRequest = new Map<K, number>();
const advance = (key: K): number => {
const request = (latestRequest.get(key) ?? 0) + 1;
latestRequest.set(key, request);
return request;
};
const stillOwned = (claimed: ReadonlyMap<K, number>): Set<K> => {
const owned = new Set<K>();
for (const [key, request] of claimed) {
if (latestRequest.get(key) === request) owned.add(key);
}
return owned;
};
return {
/** Advances keys before an authoritative write echo is installed. */
invalidate: (keys: readonly K[]): void => {
for (const key of keys) advance(key);
},
/** Advances retired keys so their pending reads cannot regain ownership. */
invalidateExcept: (active: (key: K) => boolean): void => {
for (const key of [...latestRequest.keys()]) {
if (!active(key)) advance(key);
}
},
run: async (keys: readonly K[], read: () => Promise<T>): Promise<ReadonlySet<K>> => {
const claimed = new Map<K, number>();
for (const key of keys) claimed.set(key, advance(key));
try {
const value = await read();
const owned = stillOwned(claimed);
if (owned.size > 0) land(value, owned);
return owned;
} catch (error) {
const owned = stillOwned(claimed);
if (owned.size > 0) throw error;
return owned;
}
},
};
};
export type EntityGeneration<K> = Readonly<{ key: K; generation: number }>;
/** Owns a keyed entity collection across mutation echoes and list snapshots. */
export const createLatestEntityAuthorityByKey = <K, T>(
keyOf: (value: T) => K,
land: (values: T[]) => void,
) => {
let generation = 0;
const generations = new Map<K, number>();
const pending = new Map<K, number>();
const values = new Map<K, T>();
const publish = () => land([...values.values()]);
const begin = (key: K): EntityGeneration<K> => {
const ticket = { key, generation: ++generation } as const;
generations.set(key, ticket.generation);
pending.set(key, ticket.generation);
return ticket;
};
return {
begin,
current: (key: K): T | undefined => values.get(key),
beginSnapshot: (): number => ++generation,
settle: (ticket: EntityGeneration<K>, value: T): 'landed' | 'stale' => {
if (ticket.key !== keyOf(value) || generations.get(ticket.key) !== ticket.generation) return 'stale';
values.set(ticket.key, value);
if (pending.get(ticket.key) === ticket.generation) pending.delete(ticket.key);
publish();
return 'landed';
},
settleRemoval: (ticket: EntityGeneration<K>): 'landed' | 'stale' => {
if (generations.get(ticket.key) !== ticket.generation) return 'stale';
values.delete(ticket.key);
if (pending.get(ticket.key) === ticket.generation) pending.delete(ticket.key);
publish();
return 'landed';
},
abandon: (ticket: EntityGeneration<K>): void => {
if (pending.get(ticket.key) === ticket.generation) pending.delete(ticket.key);
},
settleSnapshot: (snapshotGeneration: number, incoming: readonly T[]): void => {
const incomingByKey = new Map(incoming.map((value) => [keyOf(value), value]));
const keys = new Set([...values.keys(), ...incomingByKey.keys()]);
for (const key of keys) {
if (pending.has(key) || (generations.get(key) ?? 0) > snapshotGeneration) continue;
generations.set(key, snapshotGeneration);
const value = incomingByKey.get(key);
if (value === undefined) values.delete(key);
else values.set(key, value);
}
publish();
},
/** Lands only the named snapshot rows. Callers use this for a scoped
* reconciliation so an absent, concurrently mutating sibling is untouched. */
settleSnapshotEntries: (snapshotGeneration: number, incoming: readonly T[]): void => {
for (const value of incoming) {
const key = keyOf(value);
if (pending.has(key) || (generations.get(key) ?? 0) > snapshotGeneration) continue;
generations.set(key, snapshotGeneration);
values.set(key, value);
}
publish();
},
landLatest: (value: T): void => {
const ticket = begin(keyOf(value));
if (generations.get(ticket.key) === ticket.generation) {
values.set(ticket.key, value);
pending.delete(ticket.key);
publish();
}
},
};
};
/** Maps a potentially large read set without allowing it to fan out unbounded. */
export async function mapWithConcurrency<T, R>(
items: readonly T[],
limit: number,
read: (item: T, index: number) => Promise<R>,
): Promise<R[]> {
if (!Number.isFinite(limit) || limit < 1) throw new RangeError('limit must be at least 1');
const results = new Array<R>(items.length);
let nextIndex = 0;
const worker = async () => {
while (nextIndex < items.length) {
const index = nextIndex;
nextIndex += 1;
results[index] = await read(items[index], index);
}
};
const workerCount = Math.min(Math.floor(limit), items.length);
await Promise.all(Array.from({ length: workerCount }, worker));
return results;
}
// ── What speaks for a row when no read does ────────────────────────────────
/**
* Takes a write's echoed Agent row into the page's list.
*
* A mutation here is followed by a re-read, and for a while the re-read was the
* only thing that updated the row it moved. That is a read landing in the middle
* of the two things it must not be confused with: it can FAIL (the page toasts
* 「视图可能不是最新的」 and carries on), and it can be superseded — the authority
* above lands only the latest request and reports the rest `stale`. Either way the
* mutation returns normally over a row that still shows the pre-write state, which
* for 来源顺序 means the enrollment baseline 模型菜单与映射 diffs against is one
* write behind, and the menu's own save reports an append the ORDER write made.
*
* So the write's own answer is taken directly. Every one of these routes replies
* with the same `_agent_payload` projection the list read returns
* (`service.py:1972` returns it straight out of `set_agent_sources`), computed
* under the mutation lock after the commit — it is not a client-side prediction of
* what the write did, it is the server's own statement of what the row now is, and
* it cannot fail separately from the write that produced it.
*
* It does not make the re-read redundant: the echo is one Agent, and an order
* change also moves the source rows, the other Agents' ● 当前 and the event feed.
* It makes the re-read's LANDING stop being the only way the row can catch up.
*
* What it is not is a way to order two writes. An echo is the server's word about
* the row as of ONE commit, so it may speak for the row only while it is the
* newest word there is — and that is a fact about the writes, not something this
* function can check: two responses do not say which of them committed second.
* `createPendingWrites` below is where it is made true, by running the writes on
* a backend one at a time.
*
* A backend the page has no row for is left alone rather than appended. A write
* echo is an update to a row; which rows exist is the list read's to say.
*/
export const agentsWithEcho = (
agents: readonly AgentSupply[],
echoed: AgentSupply,
): AgentSupply[] => agents.map((agent) => (agent.backend === echoed.backend ? echoed : agent));
// ── A write that outlives the drawer that issued it ────────────────────────
/**
* Which keys have a write outstanding, where 「outstanding」 spans the read-back
* and not merely the request.
*
* It lives above the drawers rather than inside one because a drawer is not
* alive for the whole of its own write. 完成, the close X, Escape and the overlay
* all stay live while a PUT is in flight, the page unmounts the drawer when it
* closes, and reopening mints a fresh component whose local flag reads 「idle」
* over a write that is still outstanding. A flag with that lifetime is not a
* guard — it can be false while the fact is true — so everything it gates is
* ungated for exactly the user who closed and reopened, which for the order
* drawer means a hand-off to 模型菜单与映射 leaving on a baseline the page has not
* read back. `seedStep` below is the same lifetime fact met from the other side:
* the drawer's seed has to survive that reopen too, and does it by re-deriving
* from props instead of by remembering.
*
* Writes on one key run ONE AT A TIME, in the order the user made them, and the
* key stays pending from the moment an edit joins the queue until the last one
* has read back.
*
* Queued rather than concurrent, because 「the later edit wins」 is a claim about
* COMMIT order, and two PUTs in flight together settle in whatever order they
* reach the server's mutation lock. Each carries the whole list, so the loser is
* not merged into the winner, it is discarded — and the order left on disk can
* be the user's second-to-last edit while the drawer shows their last. The same
* ambiguity decides which of the two echoed rows is the newest word about the
* Agent, and nothing in the two responses says which commit came first. A queue
* makes issue order and commit order the same order, which is what the drawer's
* optimistic list and `agentsWithEcho` above were both already assuming.
*
* Counted rather than a flag per key, because 「pending」 is a property of the SET
* of writes on the key — the one running plus any waiting behind it — and the
* first to finish must not clear the key while the next is still to go.
*
* Keyed by backend because that is the write's own grain: `PUT
* /agents/<backend>/sources` moves one backend's order, so a claude write says
* nothing about codex and has no business gating or delaying it.
*/
export const createPendingWrites = (land: (keys: ReadonlySet<string>) => void) => {
const outstanding = new Map<string, number>();
const tail = new Map<string, Promise<void>>();
const publish = () => land(new Set(outstanding.keys()));
return {
/**
* Runs `work` after every write already queued on `key`, and marks the key
* pending for the whole of it — including whatever `work` awaits after its
* own request returns. Pairing is not the caller's to get right: there is no
* way to begin one without ending it.
*/
track: async (key: string, work: () => Promise<void>): Promise<void> => {
outstanding.set(key, (outstanding.get(key) ?? 0) + 1);
publish();
const mine = (tail.get(key) ?? Promise.resolve()).then(work);
// A rejected write must not break the queue behind it. The edit waiting is
// the user's newer intent and still has to reach the server — and the one
// that failed rolled its own optimistic display back, so there is nothing
// for its successor to inherit.
tail.set(
key,
mine.then(
() => {},
() => {},
),
);
try {
await mine;
} finally {
const left = (outstanding.get(key) ?? 1) - 1;
if (left > 0) outstanding.set(key, left);
else {
outstanding.delete(key);
// Nothing is queued, so the next write starts a fresh chain rather than
// hanging off a promise whose only remaining job is to be already done.
tail.delete(key);
}
publish();
}
},
};
};
/** One key's slot in the registry above, as the component issuing writes sees it. */
export type PendingWrite = {
/** Whether a write on this key is outstanding — possibly one this component
* never issued, because the component that did may already be gone. */
pending: boolean;
/** Queues `work` behind any write already outstanding on this key, and marks
* the key pending until it has read back. */
track: (work: () => Promise<void>) => Promise<void>;
};
// ── The drawers' seed ──────────────────────────────────────────────────────
// A drawer seeds its editable state from the server's saved state, and needs to
// know when that saved state MOVED. Comparing the props object is useless (every
// page refresh builds a new one), so each drawer reduces the fields it seeds from
// to a signature and compares that. The separator is NUL because these parts are
// ids: a separator that cannot occur inside one is what keeps ['a','b'] from
// colliding with ['a b'].
const sig = (parts: readonly (string | number | boolean)[]): string => parts.join('\u0000');
/** Source-order drawer: the exact ordered subset it edits. */
export const savedSourcesKey = (agent: AgentSupply): string =>
sig(agent.sources?.order ?? []);
/** OpenCode 模型菜单 drawer: the stored view + checked identifiers. */
export const savedMenuKey = (menu: AgentMenu | null | undefined): string =>
sig([menu?.view ?? 'featured', ...(menu?.checked ?? [])]);
/** What a drawer remembers about the saved state it last seeded from. */
export type SeedState = { seeded: boolean; baseline: string | null };
export const initialSeedState: SeedState = { seeded: false, baseline: null };
/**
* Whether a drawer holding `state` must re-seat itself now that the server's
* saved state reads `authoritative`.
*
* Seeds on open, and again whenever the saved state MOVED under it. Keying on
* open alone is not enough: the page unmounts a drawer when it closes, so a
* drawer closed and reopened while its own PUT is in flight seeds from the
* pre-save props and then never learns that the save landed — and its next edit
* diffs against that superseded snapshot and writes the old state back over the
* save the user already saw succeed.
*
* A refetch that changed nothing is still inert, which is the whole reason this
* compares content rather than the props object: that is what protects an edit in
* flight from a background page refresh. When the saved state genuinely moved,
* re-seating is the only honest option — a draft built on a base the server has
* replaced can only be written back as a regression.
*/
export const seedStep = (state: SeedState, authoritative: string): { state: SeedState; reseed: boolean } => {
if (state.seeded && state.baseline === authoritative) return { state, reseed: false };
return { state: { seeded: true, baseline: authoritative }, reseed: true };
};
// ── The OAuth dialog's terminal ordering ───────────────────────────────────
/**
* Every way flow state can reach the connect dialog. A `tick` is the dialog's
* own deadline check; `reset` starts a new attempt from an unsettled view.
*/
export type FlowEvent =
| { kind: 'reset' }
| { kind: 'error'; errorKey: string; failureClass: OAuthFailureClass }
| { kind: 'response'; flow: OAuthFlow }
| { kind: 'tick'; overdue: boolean };
/**
* What the caller must DO about an event. The side effects (toast, refetch,
* auto-close, stop polling) stay in the component; only the decision lives here.
*
* continue not finished, keep polling
* succeed first terminal success: fire the connected side effects, once
* fail first terminal failure: show the authority-owned error
* timeout the deadline passed with the flow unfinished
* ignore stale arrival — the dialog already finished
*/
export type FlowAction = 'continue' | 'succeed' | 'fail' | 'timeout' | 'ignore';
export type ModelHubFailureClass =
| 'authoritative-terminal'
| 'inconclusive'
| 'retryable-provider';
export type OAuthFailureClass = ModelHubFailureClass;
type ModelHubFailureEvidence = {
serverNamed: boolean;
code?: string;
detail?: string;
} | null;
const AUTHORITATIVE_TERMINAL_CODES = new Set([
'source_not_found',
'flow_settled',
'already_connected',
]);
/** One classification shared by polling, timeout recovery, and Retry. */
export const classifyModelHubFailure = (failure: ModelHubFailureEvidence): ModelHubFailureClass => {
const rawCode = failure?.code ?? failure?.detail;
const code = rawCode?.startsWith('modelHub.errors.')
? rawCode.slice('modelHub.errors.'.length)
: rawCode;
if (!failure?.serverNamed || code === 'engine_down') return 'inconclusive';
return code && AUTHORITATIVE_TERMINAL_CODES.has(code)
? 'authoritative-terminal'
: 'retryable-provider';
};
export const classifyOAuthFailure = classifyModelHubFailure;
/** Everything that decides what the dialog shows, including its terminal latch. */
export type FlowView = {
flow: OAuthFlow | null;
errorKey: string | null;
failureClass: OAuthFailureClass | null;
settled: boolean;
};
export const initialFlowView: FlowView = {
flow: null,
errorKey: null,
failureClass: null,
settled: false,
};
/**
* The states in which the SERVER has reported a flow finished — one list, because
* two places asking 「is this over?」 with two enumerations is how they drift.
*
* `timeout` is deliberately absent: it is the dialog's own verdict about a flow
* the server still considers live, which is why it arrives as a `tick` and not as
* a state at all.
*/
export const flowStateTerminal = (state: OAuthFlowState): boolean =>
state === 'success' || state === 'failed' || state === 'cancelled';
export const flowStep = (view: FlowView, event: FlowEvent): { view: FlowView; action: FlowAction } => {
if (event.kind === 'reset') return { view: { ...initialFlowView }, action: 'continue' };
// Nothing gets to change a finished flow — checked before the event is read, so
// it holds for EVERY entry point (a poll still in flight when success landed, a
// paste submit racing that poll, and the deadline tick, which used to stamp
// `failed` over a success on a dialog left open because nothing adopted the
// source).
if (view.settled) return { view, action: 'ignore' };
if (event.kind === 'error') {
return {
view: {
flow: view.flow,
errorKey: event.errorKey,
failureClass: event.failureClass,
settled: true,
},
action: 'fail',
};
}
if (event.kind === 'tick') {
if (!event.overdue) return { view, action: 'continue' };
return {
view: {
flow: view.flow ? { ...view.flow, state: 'failed' } : null,
errorKey: 'settings.models.oauth.error.timeout',
failureClass: classifyOAuthFailure(null),
settled: true,
},
action: 'timeout',
};
}
const flow = event.flow;
if (flow.state === 'success') {
return {
view: { flow, errorKey: null, failureClass: null, settled: true },
action: 'succeed',
};
}
// `settled` means terminal, not successful: a failed flow is just as finished,
// and a later arrival has just as little business reopening it. Which states
// those are is `flowStateTerminal`'s to say — success has already returned, so
// this is「terminal」and not a second, driftable list of the unsuccessful ones.
if (flowStateTerminal(flow.state)) {
return {
view: {
flow,
errorKey: flow.error_key ?? 'settings.models.oauth.error.generic',
failureClass: classifyOAuthFailure({ serverNamed: true }),
settled: true,
},
action: 'fail',
};
}
return {
view: { flow, errorKey: null, failureClass: null, settled: false },
action: 'continue',
};
};
/**
* Whether a START response has to be re-read through the status route before it
* may settle the dialog — which EVERY terminal start does.
*
* `POST …/reauth` REUSES a live pending flow — it only opens a new one once the
* old one failed or was cancelled — so a start can come back already terminal,
* and the start envelope carries the flow alone.
*
* This used to ask whether that envelope was RICH ENOUGH: a success needs the
* `{source, recovered, interrupted_pairs}` tail only status carries, while a
* failure's `error_key` is the whole message, so a failure could latch. But
* 「enough to DISPLAY」 is not 「enough to SETTLE」. Settling stops the poll — the
* next tick exits on the terminal latch — and `oauth_start` hands back the
* adapter's flow without materializing it. The materialization lives one route
* over: `oauth_status` → `_materialize_completed_oauth`, which is what runs
* `_fail_closed_hub_reauth` on an unsuccessful hub terminal, strips the discovered
* models and persists the source as 需处理. Latch a failed start and none of it
* happens: the dialog explains a failure while the row behind it still draws
* healthy and still supplies the ● 当前 it no longer can, the binding stays
* pending, and the missing write only lands when the user eventually closes the
* dialog and `oauth_cancel` performs it as a side effect of cancelling.
*
* So this does not try to know WHICH terminals owe server-side work — that is a
* fact about the server (`_is_hub_unsuccessful_terminal` is `hub` ×
* `{failed, cancelled}`, and a create's orphan cleanup keys off the retained
* material) and a guard over the envelope may not decide it. Every terminal start
* is read through the one route entitled to report a terminal; the dialog shows
* whatever that answers, and `terminalArrivalMovedRows` then re-reads the rows.
* A non-terminal start needs nothing: it is polled, as it always was.
*/
export const startNeedsStatusRead = (flow: OAuthFlow): boolean => flowStateTerminal(flow.state);
export type FlowAuthority = {
current: () => FlowView;
transition: (event: FlowEvent) => ReturnType<typeof flowStep>;
/**
* WHAT this journey is for: the source id a re-auth is repairing, or `null` for
* a create, which has no source yet.
*
* Carried on the authority because the authority is the journey's identity, and
* `flowLetGo` has to ask about the identity of a journey that is not the one
* asking — see there for the only question it answers.
*/
subject: string | null;
};
/**
* Owns the complete view, including its terminal latch, and is the only path
* that may land a new one. Keeping only `flow` at the landing site would let a
* caller silently drop `settled` and reopen an already terminal flow.
*/
export const createFlowAuthority = (
land: (view: FlowView) => void,
subject: string | null,
): FlowAuthority => {
let current: FlowView = { ...initialFlowView };
return {
current: () => current,
transition: (event) => {
const step = flowStep(current, event);
current = step.view;
land(current);
return step;
},
subject,
};
};
/** Whether an action ends the flow, so the caller stops polling. */
export const isDone = (action: FlowAction): boolean => action !== 'continue';
/**
* Whether a terminal ARRIVAL moved the rows the page behind the dialog draws.
*
* Both terminals the server reported are writes, and asking 「did it succeed?」 is
* what left one of them re-reading nothing. A success materializes the source (or
* the repair) inside the very call that first reports it. A `failed` hub reauth
* has already run `_fail_closed_hub_reauth` on its way to answering — the
* discovered models are stripped and the source is persisted as 需处理 — so the
* dialog explains a failure while the page behind it still draws that source as
* healthy, still supplying the ● 当前 it no longer can.
*
* `timeout` is not one of them, and that is the line this draws: it is the
* dialog's OWN verdict, with nothing arrived that could have written. What
* corrects the rows there is the close path, whose cancel can BE the write
* (`releaseFlow` below) and which re-reads unconditionally for that reason.
*/
export const terminalArrivalMovedRows = (action: FlowAction): boolean =>
action === 'succeed' || action === 'fail';
/**
* Whether a FAILED status poll may speak for the journey.
*
* A poll is a reader; the paste submit is the writer of record. `GET …/status`
* failing while a submit is outstanding says nothing about whether that submit
* committed — and the submit's own response is the only arrival that carries the
* terminal tail (`repaired` / `created`) at all. Latching the reader's error
* settles the view, `flowStep` above then correctly ignores the success that
* follows, and the dialog says 授权失败 over a credential the server did replace:
* no toast, no refetch, no repair verdict, on a journey that worked.
*
* Dropping it is safe precisely because the other authority is guaranteed to
* answer: the submit settles the view itself, with its success or through its own
* catch. So the flow is not left hanging on a poll — and the caller keeps reading
* meanwhile, which is what preserves the deadline for a submit that never returns.
*
* With no submit outstanding a poll IS the only authority — but only when the ROUTE
* answered. That same materializing call is the reason: a status read that commits
* the create or the repair and then loses its response (a dropped connection, a
* proxy's HTML 502, a body that will not parse) throws a failure `call()` minted,
* not one the server named. Settling on it declares a terminal nobody reported, over
* an operation that may have committed — the dialog says 授权失败 on a source the
* server did create, and an ordinary connect retried from there mints a second one.
* `classifyOAuthFailure` owns that discriminator: a refusal that named itself can
* answer about the flow, while an inconclusive class cannot.
*
* Dropping it is bounded either way — the caller keeps polling, and the deadline at
* the top of each tick is the dialog's own verdict when nothing ever answers.
*/
export const pollFailureSettles = (
submitOutstanding: boolean,
failureClass: OAuthFailureClass,
): boolean => !submitOutstanding && failureClass !== 'inconclusive';
/**
* Whether the failure that just arrived is the one now ON SCREEN.
*
* `flowStep` answers `ignore` to everything that reaches a view already settled, so
* a paste submit rejecting after the poll latched `discovery_failed` leaves the
* sentence the user is reading belonging to the POLL. The stranded pairs render
* directly beneath that sentence, as the cost of the failure it names, so they may
* only come from the arrival that produced it: the late one's own list is empty —
* the write that stranded those rows happened on the other request — and would
* erase the gap report rather than restate it.
*
* Deliberately not `terminalArrivalMovedRows`, which reads the same `action` to
* answer a different question. Whether a request may have WRITTEN is independent of
* whether it may SPEAK, and the refetch beside these pairs is owed either way.
*/
export const failureLanded = (action: FlowAction): boolean => action === 'fail';
/**
* Whether a journey may walk away from the flow it opened without cancelling it —
* i.e. whether SOMEONE ELSE can still be handed that exact flow.
*
* Three facts have to agree, and each answers a different question:
*
* 1. Ownership — 「is it still mine to cancel?」 `POST …/reauth` REUSES a live
* pending flow, so a teardown that cancels after ownership moved does not clean
* up after itself: it ends the login the user is watching in the dialog that
* replaced it. The answer therefore depends on WHEN a path asks. The effect's
* own cleanup asks at the instant ownership transfers and still holds it, while
* a start whose dialog closed mid-request asks after that same cleanup already
* released it. Identical call, right in one place and wrong in the other.
* 2. The route — 「could it EVER have become someone else's?」 `oauth_start` mints a
* fresh pending source id on every call and never looks for a pending flow, so
* a create's flow belongs to the one journey that opened it. Ownership alone
* cannot say this, which is why `routeReuses` is asked separately: on a create
* there is no successor coming for that flow at all, so it dies with the journey
* that opened it.
* 3. The successor's SUBJECT — 「could this particular one be handed my flow?」
* `pending_reauth(source_id)` filters on `binding.source_id`, so the handover is
* keyed by SOURCE while ownership of this ref is global to the dialog. Close a
* pending re-auth for source A, open one for source B before A's start returns,
* and A finds a live owner that can never adopt its flow: withholding the cancel
* there leaves A's authorization running until it expires. So the route being
* reusable is a claim about a class of successors, not about whoever happens to
* hold the ref.
*
* A `null` owner is NOT let go, and that is a fact about this dialog rather than a
* preference. Every successor takes authority SYNCHRONOUSLY in the effect body —
* `flowAuthorityRef.current = authority` in `OAuthConnectDialog.tsx`, before the
* start request is awaited — so a successor that exists has already put itself
* there by the time any late response reads the ref. `null` therefore cannot mean
* 「a successor is about to」; it means the user closed the dialog and did not
* reopen it.
*
* An earlier revision read it the other way and withheld the cancel to protect a
* flow some future start might adopt. What that actually left behind was a live
* authorization the user had just cancelled: the server holds it until it times
* out, and the next re-auth for that source is handed exactly that flow and can
* materialize it — a login the user declined, completing later. A start after the
* cancel just mints a fresh flow, so the real trade is one extra round trip
* against honouring 取消, and only a successor that EXISTS may suppress it.
*/
export const flowLetGo = (
journey: FlowAuthority,
owner: FlowAuthority | null,
routeReuses: boolean,
): boolean =>
owner !== null &&
owner !== journey &&
routeReuses &&
owner.subject === journey.subject;
/**
* Hands back the flow a journey opened, and is the ONLY authorization for a
* teardown cancel.
*
* Whether the cancel is authorized is `flowLetGo`'s call — see there for the three
* separate facts that have to agree before a journey may walk away from a flow.
*
* Rereading is unconditional, and this function is not given the flow so that no
* caller can argue otherwise from it. `POST /oauth/cancel` is not always a
* cancel — `oauth_cancel` routes a `success` flow, and a failed hub reauth, into
* `_materialize_completed_oauth` — so the call can BE the write. The only state a
* caller could branch on is the last POLLED snapshot, which an in-flight poll or
* a paste submit can terminalize between that read and the cancel landing. An
* earlier revision branched on exactly that, from a list named `TERMINAL`;
* naming a snapshot after a fact did not make it one.
*
* A `null` cancel means the journey never got a flow id — there is no call to
* make, which is not the same as deciding not to make one.
*/
export const releaseFlow = async (
journey: FlowAuthority,
owner: FlowAuthority | null,
ops: {
cancel: (() => Promise<unknown>) | null;
reread: () => void;
/** Whether the ROUTE can hand this same flow to a successor journey. */
reusable: boolean;
},
): Promise<void> => {
if (ops.cancel && !flowLetGo(journey, owner, ops.reusable)) {
try {
await ops.cancel();
} catch {
// Nothing to show — the dialog this belonged to is already gone. The reread
// below still has to run: the writes upstream of this call do not depend on
// it succeeding.
}
}
ops.reread();
};