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
import type { TranslationKey } from '@/i18n/types';
// The supply JOURNEYS' decisions — which remedy a stopped source actually has,
// what the server's answer to a repair means, and whether 试跑 has anything real
// to run. Same shape and same reason as `supply.ts` / `sufficiency.ts`: each of
// these is a judgement the components are not free to improvise, this repo's
// vitest has no DOM, so they are plain functions over the contract types.
//
// §4.5 is what makes the first one load-bearing: `needs_action` 「carries a
// detail_key naming the cause, so the row can offer ONE TAP to fix it (re-auth,
// top up, replace key) instead of a dead-end error string」. A row that renders
// the cause and stops is the dead end that sentence forbids.
import type {
AgentBackend,
AgentSupply,
ProbeErrorKey,
ProbeResult,
Source,
SourceDetailKey,
SourceRepaired,
SourceState,
SupplyChannel,
SupplyGap,
} from './types';
/**
* The two statuses a repair can recover from, and the exact set the server calls
* `recovered` over (`state.status in {needs_action, error}`).
*
* Deliberately NOT `needsAttention`, which is wider by one: an 额度用完 cooldown
* earns the gold sub-line but heals itself on the billing cycle, and offering it
* a repair button would put a one-tap fix on the one blocker that does not need
* one. Deliberately NOT `isUnhealthy` either, which is wider by all three
* cooldowns. Three predicates, three different questions.
*/
export const wasBlocked = (state: SourceState): boolean =>
state.status === 'needs_action' || state.status === 'error';
// ── Which remedy a source HAS (independent of whether it needs one) ──────
// These three mirror the server's own preconditions, one for one, so the menu
// offers exactly the actions the routes accept. The elective entries read these;
// the blocked row's inline button reads `repairAction` below.
/** `POST …/reauth` accepts subscriptions on BOTH channels — a hub-held grant is
* re-obtained by logging in again just as a native CLI login is. */
export const canReauth = (source: Source): boolean => source.kind === 'subscription';
/** `PUT …/credential` is hub-channel api_key only, and needs an existing
* credential to replace (`kind != api_key || channel != hub || !credential_ref`
* ⇒ `discovery_failed`). */
export const canReplaceKey = (source: Source): boolean =>
source.kind === 'api_key' && source.supply_channel === 'hub' && Boolean(source.credential_ref);
/** `POST …/refresh` is the contract's ONE recovery endpoint (「v3 does not add a
* second 'recover' endpoint」) and rejects native sources, which have nothing to
* re-discover. */
export const canRetest = (source: Source): boolean =>
source.supply_channel === 'hub' && source.protocol !== 'search';
/** Search Sources have a dedicated recovery check; model refetch is forbidden for them. */
export const canReenable = (source: Source): boolean =>
source.protocol === 'search' && source.kind === 'api_key' && source.supply_channel === 'hub';
/** What a stopped row offers as its one tap. */
export type RepairKind = 'reauth' | 'replace_key' | 'retest' | 'reenable';
/** Causes whose fix is a NEW credential, held by Avibe: the grant or the key
* itself stopped working, and only replacing it can help. */
const CREDENTIAL_CAUSES: ReadonlySet<SourceDetailKey> = new Set<SourceDetailKey>([
'models.source.needs_action.oauth_expired',
'models.source.needs_action.credential_revoked',
]);
/** 「The last sign-in produced nothing usable」 — the whole of `ErrorDetailKey`,
* and on a native source the only blocker another sign-in can actually clear.
* Rule 3 in `repairAction` is what reads it. */
const SIGN_IN_INCOMPLETE: SourceDetailKey = 'models.source.error.unclassified';
/**
* The one-tap remedy for a blocked source, or null when it genuinely has none.
*
* Two rules, no per-cause table:
*
* 1. The credential itself failed → replace it, by the route that owns that
* source's kind of credential (login for a subscription, key for an api_key).
* 2. Anything else → Avibe cannot name the cause and must not pretend to; what
* it can do is stop guessing and re-check, which is exactly what the recovery
* test is for. The row's affordance is 「handled it — retry」, not 「top up
* here」, because no contract field carries a vendor billing URL and a button
* that cannot go there would be the dead end again.
* 3. …unless the source has no recovery test at all (native) AND its blocker is
* the one a fresh sign-in clears — then re-login, because rule 2 would
* otherwise leave that row with no tap whatsoever. Narrow on purpose: the
* branch comment carries the cost argument for why it is not every cause.
*
* A healthy source has no remedy to offer because it has no problem — the caller
* renders nothing, not a disabled button.
*/
export function repairAction(source: Source): RepairKind | null {
if (!wasBlocked(source.state)) return null;
const credentialFailed = Boolean(source.state.detail_key && CREDENTIAL_CAUSES.has(source.state.detail_key));
if (credentialFailed) {
if (canReauth(source)) return 'reauth';
if (canReplaceKey(source)) return 'replace_key';
return null;
}
if (canReenable(source)) {
return source.state.detail_key === 'models.source.needs_action.balance_exhausted'
|| source.state.detail_key === 'models.source.needs_action.spend_limit_reached'
? 'reenable'
: null;
}
if (canRetest(source)) return 'retest';
// Native has no recovery refresh — `refresh_source` refuses `native_cli` outright — so
// rules 1 and 2 together leave a stopped native row with no tap at all, its
// remedy surviving only in the overflow menu. Rule 3 covers the one cause where
// signing in again is the answer rather than a guess, and the cause matters
// because this fallback SPENDS something: a native re-login invalidates the
// current sign-in before the vendor page even loads (`reauthCost` below), so
// offering it for a blocker it cannot fix is the §4.5 dead end plus a bill.
//
// `error.unclassified` earns it. It is the only key `ErrorDetailKey` holds, and
// it reaches a NATIVE source from exactly two places, both inside a native
// re-login: `completed_source_status` threw, or post-login discovery came back
// empty. It means 「that sign-in produced nothing usable」, so another one is the
// convergent recovery — and without this the two sibling writes of one backend
// helper contradict each other, `_mark_native_reauth_unavailable`'s needs_action
// branch keeping the button (its key is a credential cause) while its error
// branch loses it. A declared upstream cause like 余额耗尽 does NOT earn it, and
// the native/`account_banned` case in `repair.test.ts` is that boundary.
return source.state.detail_key === SIGN_IN_INCOMPLETE && canReauth(source) ? 'reauth' : null;
}
/**
* A remedy's label key. A Record over the union, never a template literal:
* `t(`settings.models.repair.${kind}`)` compiles for every member and then
* renders the raw key path for the one the bundle spells differently
* (`replace_key` → `replaceKey`), which is what a blocked api_key row showed. As
* a Record the compiler refuses a new RepairKind that has no label, and
* `repair.test.ts` proves each one is translated in both locales.
*/
export const REPAIR_LABEL_KEY: Record<RepairKind, TranslationKey> = {
reauth: 'settings.models.repair.reauth',
replace_key: 'settings.models.repair.replaceKey',
retest: 'settings.models.repair.retest',
reenable: 'settings.models.repair.reenable',
};
/**
* The concrete control each remedy reaches. This is deliberately another total
* Record over `RepairKind`: a label without a destination is still the dead end
* this module exists to prevent. `retest` names the existing refetch control,
* rather than being treated as an exception by the component or its test.
*/
export type RepairDestination = 'reauth_dialog' | 'replace_key_dialog' | 'refetch_button' | 'reenable_button';
export const REPAIR_DESTINATION: Record<RepairKind, RepairDestination> = {
reauth: 'reauth_dialog',
replace_key: 'replace_key_dialog',
retest: 'refetch_button',
reenable: 'reenable_button',
};
/**
* What STARTING a re-login costs on this source's channel — the confirm's whole
* subject, and the one thing about it the two channels do not share.
*
* `immediate`: a native re-login is irreversible up front.
* `mark_native_irreversible_start` runs as the login spawns and rewrites every
* native source of that vendor's backend to 需要处理 with its discovered models
* stripped; it is rolled back only when the login fails to SPAWN. The price is
* paid on 「开始」, whatever happens next.
*
* And it is not paid back in full: the sentence has to say so, because success
* restores only the source the dialog is about. `_materialize_completed_oauth`
* re-discovers onto THAT one; its siblings on the shared CLI keep the empty
* inventory and the 需处理 the start wrote, each needing its own sign-in
* (`tests/test_model_hub_api.py::test_native_reauth_invalidates_sibling_sources_for_shared_cli`).
* 「until you finish」 alone reads as a wait, which is the one thing this is not.
*
* `on_failure`: a hub re-login writes nothing at start — the held credential goes
* on working while the user signs in. The cost arrives only if the flow comes
* back `failed`, where `_fail_closed_hub_reauth` marks the source 需要处理 because
* Avibe cannot tell whether the vendor invalidated the old grant. Closing the
* dialog cancels the flow, and a cancelled flow is not a failed one.
*
* Two costs, two sentences. One sentence over both is false on one of them, and
* 「the old sign-in stops working as soon as you start」 is false on hub in the
* direction that matters: it warns about a loss that does not happen, and says
* nothing about the one that does.
*/
export type ReauthCost = 'immediate' | 'on_failure';
export const reauthCost = (source: Source): ReauthCost =>
source.supply_channel === 'native_cli' ? 'immediate' : 'on_failure';
const REAUTH_BODY_KEY: Record<ReauthCost, TranslationKey> = {
immediate: 'settings.models.repair.reauthBody.immediate',
on_failure: 'settings.models.repair.reauthBody.onFailure',
};
/** The confirm body that is TRUE for this source. */
export const reauthBodyKey = (source: Source): TranslationKey => REAUTH_BODY_KEY[reauthCost(source)];
// ── What the server's repair answer MEANS ────────────────────────────────
/**
* The verdict over a repair tail — the single owner of 「did that fix it?」, so
* the toast, the dialog's closing behaviour and the gap report cannot disagree.
*
* All three inputs are the server's own: `interrupted_pairs` is the output of the
* very guard that would have refused the write, `source.state` is where the write
* left the source, and `recovered` is its judgement that the source HAD been
* blocked. Nothing is re-derived here — a client that recomputed 「is anything
* stranded?」 from `/agents` would be answering a different question (today's
* supply) than the one it renders.
*
* The order is the point:
*
* 1. `gaps` outranks everything. A forced replacement that fixed this source
* while stranding another Agent's model is not a success story, and the
* report is the whole reason the user was asked to confirm.
* 2. Then the RETURNED STATE, because `recovered` is a statement about the past
* — 「it was blocked when this started」 — and cannot claim the source works
* now. A native reauth reaches exactly that case: `_materialize_reauth`
* commits `needs_action`/`oauth_expired` when the CLI still reports itself
* signed out, and answers 200 with `recovered: true` beside it. Reading
* `recovered` alone would put 「已恢复可用」 on a row that is still stopped and
* dismiss the dialog over it.
* 3. Only then 「was it broken before?」, which separates a repair from the
* elective rotation of a working credential.
*/
export type RepairOutcome =
| { kind: 'repaired' }
| { kind: 'refreshed' }
| { kind: 'unresolved' }
| { kind: 'gaps'; gaps: SupplyGap[] };
export const repairOutcome = (tail: SourceRepaired): RepairOutcome =>
tail.interrupted_pairs.length > 0
? { kind: 'gaps', gaps: tail.interrupted_pairs }
: wasBlocked(tail.source.state)
? { kind: 'unresolved' }
: tail.recovered
? { kind: 'repaired' }
: { kind: 'refreshed' };
/**
* Whether the journey may close itself.
*
* Provable from the tail alone: 「nothing was stranded, and the source came back
* working」 is two fields the server sends.
*
* An allowlist rather than `!== 'gaps'`: a plain success closes on its toast,
* and every other verdict leaves an instruction on screen that a toast cannot
* hold. Written as an exclusion, the next verdict added would inherit the close
* silently, which is the wrong default for a verdict that exists because
* something did not work.
*/
export const repairSettles = (outcome: RepairOutcome): boolean =>
outcome.kind === 'repaired' || outcome.kind === 'refreshed';
/**
* A verdict's one line, by the same rule as `REPAIR_LABEL_KEY` above: the key is
* looked up, never assembled.
*
* `gaps` is absent deliberately, and the type says so — a gap report is a heading
* (`gapsDone`) over a list of pairs, not a sentence, so every caller branches on
* it before reaching this map and the compiler holds them to it.
*/
export type RepairLine = Exclude<RepairOutcome['kind'], 'gaps'>;
export const REPAIR_LINE_KEY: Record<RepairLine, TranslationKey> = {
repaired: 'settings.models.repair.repaired',
refreshed: 'settings.models.repair.refreshed',
unresolved: 'settings.models.repair.unresolved',
};
/**
* A verdict's TOAST — the line and the tone, decided together, for every kind.
*
* The toast is not the panel. A gap report renders there as a heading over a list
* of pairs, which is why the map above has no `gaps` entry; a toast has no list, so
* it needs a sentence for the one verdict that panel handles structurally.
*
* Tone belongs here for the reason the gap case proves: written at the call site as
* 「warning if unresolved, success otherwise」, the gap report got the one tone that
* contradicts its own text — a green 「连接成功」 over a dialog reporting that Agents
* now have no source at all. Tone is a property OF the verdict, not of the branch
* that happens to render it, and a Record over the full union makes the next
* verdict added answer for its own tone instead of inheriting green.
*/
export const REPAIR_TOAST: Record<RepairOutcome['kind'], { key: TranslationKey; tone: 'success' | 'warning' }> = {
repaired: { key: REPAIR_LINE_KEY.repaired, tone: 'success' },
refreshed: { key: REPAIR_LINE_KEY.refreshed, tone: 'success' },
// The call succeeded and the source is still stopped: this page's gold 需处理
// tone, not a red failure.
unresolved: { key: REPAIR_LINE_KEY.unresolved, tone: 'warning' },
gaps: { key: 'settings.models.repair.gaps', tone: 'warning' },
};
// ── 试跑 (dry run) ───────────────────────────────────────────────────────
export type DryRunPlan = { kind: 'probe'; backend: AgentBackend } | { kind: 'none' };
/** A dry run exists only while a managed Agent has a runnable supply rollup. */
export function dryRunPlan(agent: AgentSupply): DryRunPlan {
if (agent.mode !== 'hub') return { kind: 'none' };
if (agent.supply_status !== 'ok' && agent.supply_status !== 'degraded') return { kind: 'none' };
return { kind: 'probe', backend: agent.backend };
}
/** A source's name for copy, falling back to its id — the same tolerance
* the source rows keep for an id that no longer resolves. */
const nameOf = (sources: Source[], id: string): string =>
sources.find((s) => s.id === id)?.display_name || id;
/**
* The probe's own verdict, named for copy. `reachable` is the discriminator the
* contract pins (`error` is null iff reachable), so nothing else is consulted.
*
* A null `latencyMs` is not a missing measurement, it is the answer for a head
* the Hub does not carry the request for: the caller says 「可用」 without a
* number rather than printing a zero it did not measure.
*
* One copy constraint the key names badly: `models.probe.native_cli_unavailable`
* is NOT 「you are not signed in」. `_default_native_cli_ready` returns false when
* an ANTHROPIC_/OPENAI_ key or base-url overrides the CLI's own sign-in, when a
* codex login is genuinely absent, AND for every backend that has no native
* channel at all. The first case is the common one, and there the sign-in is
* perfectly valid — so the string states that the sign-in cannot be used and
* instructs nothing, the same rule that stopped `oauth_expired` from claiming a
* wall-clock expiry it cannot prove.
*/
export type DryRunOutcome =
| { kind: 'ok'; sourceName: string; latencyMs: number | null; channel: SupplyChannel }
/** v4 widened the key set past `state.detail_key`: the native branch reports
* process unavailability, the case the paragraph above is about, and no
* source-state key can express it. */
| { kind: 'failed'; sourceName: string; detailKey: ProbeErrorKey | null; channel: SupplyChannel };
export function dryRunOutcome(probe: ProbeResult, sources: Source[]): DryRunOutcome {
const sourceName = nameOf(sources, probe.source_id);
return probe.reachable
? { kind: 'ok', sourceName, latencyMs: probe.latency_ms, channel: probe.channel }
: { kind: 'failed', sourceName, detailKey: probe.error, channel: probe.channel };
}
/**
* Did that probe leave a mark on the server? 试跑 is a real turn, so a failing
* one is not a read: `probe_agent` routes the failure through `_cooldown` or
* `_set_source_blocker`, which changes the source's health and can move the
* Agent's head and supply rollup with it. A caller that only stores the verdict
* shows the row states the failure just invalidated.
*
* Deliberately 「any unreachable probe」 rather than 「an unreachable hub probe」.
* The native branch answers from `native_source_ready` and returns before the
* write block, so today it writes nothing — but keying on the channel would
* oblige every reader to track which branch writes, and the cost of being wrong
* is a stale page, while the cost of the extra read is one request on a button
* the user pressed. A reachable probe is the case that provably writes nothing:
* the write block sits entirely under `if not reachable`, and no path clears a
* cooldown on success.
*
* A thrown probe the server NAMED needs no re-read for the same reason, checked
* outcome by outcome: `probe_no_candidate` is raised before any write, and an
* engine failure propagates out of `_engine_call` above the write block. A throw
* the server did not name is not one of those outcomes — see `probeArrival`.
*/
export const probeWroteState = (probe: ProbeResult): boolean => !probe.reachable;
/**
* Whether a caught failure leaves the server's state UNKNOWN to us — the one
* question two dialogs and this drawer all had to answer, so it lives once.
*
* `serverNamed` is the error's own account of where its code came from: the
* transport mints `bad_response` for a body that would not parse and `http_<n>`
* for one that parsed saying nothing, and a request that reached the route and
* lost its answer coming back is exactly as consistent with 「it committed」 as
* with 「it never ran」. A failure with no name is not one of the route's
* enumerated outcomes, so nothing about it can be checked outcome by outcome.
*
* `null` — a throw that is not an `ApiCallError` at all — counts as unknown for
* the same reason and one more: reaching it means our own code threw AFTER the
* await, which puts the server's write strictly in the past.
*/
export const mayHaveWritten = (failure: { serverNamed: boolean } | null): boolean =>
!(failure?.serverNamed ?? false);
/**
* Refusals whose ARRIVAL disproves what the page was already drawing, whether or
* not they wrote anything.
*
* `probe_no_candidate` is the case: it is raised before any write (the chain
* payload is computed, no runnable item is found, nothing is saved), so
* `mayHaveWritten` is correctly false for it — and yet the 试跑 control the user
* pressed was rendered from a loaded chain WITH a head, so the refusal is the
* server saying that head is gone. Another turn, or another client, cooled or
* blocked it in between. `direct_mode` is the same sentence about the mode: the
* drawer only offers a chain for an agent it believes is in hub mode.
*
* Leaving those two un-reread is the one stale state the user cannot clear by
* looking: the chip still names a source and the button still invites a run that
* cannot happen. A write is one reason to re-read; being contradicted is another,
* and they are independent.
*/
const STATE_PRECONDITION_REFUSALS = new Set(['probe_no_candidate', 'direct_mode']);
export const disprovedDrawnHead = (code: string | null): boolean =>
code !== null && STATE_PRECONDITION_REFUSALS.has(code);
/**
* What a probe's arrival still gets to do. Two questions that look like one and
* are not: whether this answer may be SHOWN, and whether the page behind the
* sheet has to be RE-READ.
*
* They come apart the moment the user edits the chain while a probe is in flight.
* The edit bumps the sequence, so the response stops being the answer to anything
* on screen — and dropping it there dropped the acknowledgment that it WROTE.
* Nothing else covers that: the edit's own PUT refetch is issued while this probe
* is still out, so it can read the source back exactly as it was before the
* cooldown landed, leaving a healthy row and a ● 当前 the server has already
* moved. Staleness is a fact about the QUESTION; the write is a fact about the
* server, and no guard over the first may decide the second.
*
* A THROW is the same split with a different answer to the second half.
* `probeWroteState`'s outcome-by-outcome check covers the failures the route
* NAMES, and every one of those arrives as a structured `ApiCallError`. A throw
* with no server name is not one of the route's outcomes at all — a lost
* connection, an unparseable body — so the probe may have run and written with
* the response never reaching us. Unknown is not the same as no, and this takes
* `probeWroteState`'s own trade: one extra read costs a request, while being
* wrong the other way costs a page that silently disagrees with the server.
*
* And a re-read is owed for a SECOND reason that has nothing to do with writing:
* a refusal can arrive that contradicts the state the page is drawing from
* (`disprovedDrawnHead`). The two are independent — `probe_no_candidate` writes
* nothing and still disproves the head — so they are asked separately and only
* their answers are combined.
*/
export type ProbeAnswer =
| { kind: 'result'; probe: ProbeResult }
/** `serverNamed` is the error's OWN account of where its code came from
* (`ApiCallError.serverNamed`), which is what makes it one of the checked
* outcomes. Not 「is it one of ours?」: the transport mints `bad_response` and
* `http_<n>` itself for a response that never said what happened, and those
* are the exact answers this exists for — a probe that ran, wrote, and lost
* its reply on the way back throws one of ours with nothing named in it.
* `code` is that name when there is one, for the refusals whose arrival is
* itself news about the chain. */
| { kind: 'thrown'; serverNamed: boolean; code: string | null };
export type ProbeArrival = {
/** Whether this answer is still the answer to what the row is asking. */
report: boolean;
/** Whether the source rows and serving-chain status are now stale. */
reread: boolean;
};
export const probeArrival = (answer: ProbeAnswer, stillCurrent: boolean): ProbeArrival => ({
report: stillCurrent,
reread:
answer.kind === 'result'
? probeWroteState(answer.probe)
: mayHaveWritten(answer) || disprovedDrawnHead(answer.code),
});
export type DryRunRowView = {
backend: AgentBackend | null;
enabled: boolean;
report: boolean;
};
/** Keep a completed report visible even when its probe changes supply health. */
export const dryRunRowView = (
plan: DryRunPlan,
row: { line: string | null; saving: boolean; running: boolean },
): DryRunRowView => {
const backend = plan.kind === 'probe' ? plan.backend : null;
return {
backend,
enabled: backend !== null && !row.saving && !row.running,
report: row.line !== null,
};
};