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 { BackendConnectionState, VibeAgentBrief, VibeAgentFull, CliStatus } from '../../context/ApiContext';
import type { CollectionReadAuthority } from '../settings/models/collectionReadAuthority';
import { runtimeIsRunning } from '../settings/models/runtimeLifecycle';
import type { AgentSupply, RuntimeDependency, SupplyStatus } from '../settings/models/types';
import { BUILTIN_BACKENDS, isBuiltinBackend, type AgentBackendId } from '@/lib/agentBackends';
import { ASSISTANT_ORDER, type AssistantId } from './collaborationTimeline';
import { readSetupTargets } from './setupTargets';
/**
* C4 — the gate setup's last click has to pass.
*
* The rule this file exists for: **one assistant must satisfy the whole gate.** Three
* independent existential checks can each be met by a different object — an enabled
* Codex with no route, a route persisted against an uninstalled Claude, a healthy
* source neither of them uses — and setup would finish on a machine whose first
* workspace turn cannot run. So every condition below is joined to the same candidate,
* by backend AND by Agent name, and every one of them is read from the server.
*
* Kept stateless and separate from the Wizard for the same reason `gatewayBootstrap`
* is: the interesting part is a decision over evidence, and a decision over evidence
* can be stated as data and tested without a React tree.
*/
/** One named Agent that satisfies the gate, with the model the server resolved for it. */
export type EntryCandidate = {
agent: VibeAgentBrief;
backend: AgentBackendId;
modelId: string;
};
/**
* The order the gate offers candidates in, which is the order setup picks a default
* from: the CLI assistants first and a built-in backend last. That is the server's
* `implicit_default_rank` — making the built-in assistant the default is its own
* decision, so setup only falls back to it when no CLI assistant can run (D3).
*/
const ENTRY_ORDER: readonly AgentBackendId[] = [...ASSISTANT_ORDER, ...BUILTIN_BACKENDS];
export type EntryEvidence = {
/** False when the Agent listing itself failed. An empty list and an unread list are
* different facts, and only one of them is something the person can act on. */
agentsRead: boolean;
agents: readonly VibeAgentBrief[];
defaultAgentName: string | null;
/** Designated builtins from uncached full-Agent metadata; empty when none can be proved. */
targets: readonly VibeAgentBrief[];
connections: readonly BackendConnectionState[];
/** False when the shared collection refresh threw; empty supplies then mean unread, not none. */
suppliesRead: boolean;
supplies: readonly AgentSupply[];
/** Null when the Hub runtime read threw or did not answer. Unread is not "running". */
runtime: RuntimeDependency | null;
/** Per-backend detection health for that configured path; missing evidence is not healthy. */
cliHealthy: Readonly<Record<AssistantId, boolean>>;
};
/**
* Why nothing was admitted, named as the sentence the person is owed.
*
* Each value is an existing `onboarding.connection.*` key, and each keeps the
* situation it already described: nothing eligible at all, a machine that has not
* applied its configuration yet, and — now also covering the route join — a machine
* that is up but has no assistant that could actually run a turn.
*/
export type EntryRefusal = 'entryFailed' | 'applyPending' | 'modelUnavailable';
export type EntryAdmission =
| { kind: 'admitted'; candidates: EntryCandidate[] }
| { kind: 'refused'; reason: EntryRefusal; startable: boolean };
/** A configured route whose sources are all unusable is not a runnable route. */
const RUNNABLE_SUPPLY: ReadonlySet<SupplyStatus> = new Set<SupplyStatus>(['ok', 'degraded']);
const usableAgent = (agent: VibeAgentBrief): boolean => agent.enabled && !agent.archived;
const isRecord = (value: unknown): value is Record<string, unknown> =>
typeof value === 'object' && value !== null && !Array.isArray(value);
/**
* The configured CLI path the gate must detect, from the already-fresh prerequisite.
*
* A persisted `agents.<backend>.cli_path` wins. When none is configured, the existing
* detect path falls back to the backend name — the same default AgentDetection uses.
*/
export function configuredCliPath(config: Record<string, unknown> | undefined, backend: AssistantId): string {
const agents = config && isRecord(config.agents) ? config.agents : undefined;
const row = agents && isRecord(agents[backend]) ? agents[backend] : undefined;
if (row && typeof row.cli_path === 'string' && row.cli_path.trim()) return row.cli_path.trim();
return backend;
}
/**
* Whether this candidate's assistant is enabled, applied, in custody, and actually on disk.
*
* Installed is not `connection.installed`. C4 asks for `detectCli(configured path)`
* and a current-generation `refresh()` whose `cli_present` agrees, plus
* `getBackendConnection.enabled`. A failed detector, a not-found binary, or a stale
* refresh cannot be replaced by the connection's own installed bit.
*
* A built-in backend has no CLI to be on disk (D3): it is part of the platform, so
* its applied connection and the runnable route below are the whole of its gate.
*
* `ready` carries permission and credential ownership; `applied` is the only
* application state that means the configuration is live. A confirmed `stopped` is
* something to recover from, never something to enter on.
*/
const backendUsable = (
backend: AgentBackendId,
connection: BackendConnectionState | undefined,
supply: AgentSupply | undefined,
cliHealthy: Readonly<Record<AssistantId, boolean>>,
): boolean =>
connection !== undefined && connection.ok
&& connection.enabled
&& connection.ready && connection.application === 'applied'
&& supply !== undefined
&& (isBuiltinBackend(backend)
|| (supply.cli_present === true && cliHealthy[backend as AssistantId] === true));
/**
* Whether the server can route THIS named Agent to a model right now.
*
* Deliberately not `selected_model_id`: that is the backend-level pick belonging to
* `selected_by_agent`, so reading it would let one Agent's configuration speak for
* another's. The runnable-hop owner is the server resolver, and its per-Agent answer
* is the `named_agents` row — an absent row is a backend that never routed this name.
*/
export const routeRunnable = (supply: AgentSupply | undefined, name: string): string | null => {
if (!supply || supply.mode !== 'hub') return null;
const row = supply.named_agents?.find((named) => named.name === name);
if (!row || row.route_reason === 'route_unconfigured') return null;
if (!row.effective_model_id || !row.supply_status || !RUNNABLE_SUPPLY.has(row.supply_status)) return null;
return row.effective_model_id;
};
/** Every Agent that passes the whole gate, in `ENTRY_ORDER` and then by name. */
export function entryCandidates(evidence: EntryEvidence): EntryCandidate[] {
// Mode alone is not runtime readiness: a backend can be in hub mode while the Hub
// that would serve it is down, and then no route on this machine is runnable.
// An unread runtime is the same: we did not observe it, so we may not admit on it.
if (!evidence.runtime || !runtimeIsRunning(evidence.runtime) || !evidence.suppliesRead) return [];
const connectionOf = new Map(evidence.connections.map((connection) => [connection.backend, connection]));
const supplyOf = new Map(evidence.supplies.map((supply) => [supply.backend, supply]));
return ENTRY_ORDER.flatMap((backend) => {
if (!backendUsable(backend, connectionOf.get(backend), supplyOf.get(backend), evidence.cliHealthy)) return [];
return evidence.agents
.filter((agent) => agent.backend === backend && usableAgent(agent))
.flatMap((agent) => {
const modelId = routeRunnable(supplyOf.get(backend), agent.name);
return modelId ? [{ agent, backend, modelId }] : [];
})
.sort((left, right) => (left.agent.name < right.agent.name ? -1 : left.agent.name > right.agent.name ? 1 : 0));
});
}
/**
* Whether a refusal is one an explicit start may still resolve.
*
* Only a connection the server confirmed `stopped` counts. Pending, draining, failed
* and unknown are not confirmations, and a browser may not turn "I could not tell"
* into a request to start something. Startup itself has no assistant, source, or
* `entry_eligible` prerequisite — those belong to the gate after recovery.
*/
const startable = (connections: readonly BackendConnectionState[]): boolean =>
!connections.some((connection) => connection.ready)
&& connections.some((connection) => connection.ok && connection.application === 'stopped');
export function admitEntry(evidence: EntryEvidence): EntryAdmission {
const candidates = entryCandidates(evidence);
if (candidates.length) return { kind: 'admitted', candidates };
const connections = evidence.connections.filter((connection) => connection.ok);
const reason: EntryRefusal = !evidence.agentsRead || !connections.some((connection) => connection.entry_eligible)
? 'entryFailed'
: !connections.some((connection) => connection.ready)
? 'applyPending'
// The machine is up and in custody, so what is missing is the run itself: no
// enabled Agent to run, or none the Hub can route to a model.
: 'modelUnavailable';
return { kind: 'refused', reason, startable: startable(connections) };
}
/**
* The Agent setup should enter on, or `null` when the saved default already serves.
*
* A default someone chose is preserved whenever it still works, including a custom
* Agent no card represents — setup is finishing a machine, not imposing its own
* preference on one. Only when the saved name cannot run does setup pick, and then it
* prefers the assistant's own Agent so the first workspace turn matches the card the
* person was just looking at. That preference applies within the first rank that can run
* — the CLI assistants before the built-in backend, as `ENTRY_ORDER` ranks them — so any
* runnable CLI assistant's Agent, its own or a custom one, wins over the built-in one.
*/
export function chooseEntryDefault(
candidates: readonly EntryCandidate[],
evidence: EntryEvidence,
): EntryCandidate | null {
if (candidates.some((candidate) => candidate.agent.name === evidence.defaultAgentName)) return null;
// The preference for an assistant's own Agent applies within the first rank that can
// run: a runnable CLI assistant's custom Agent still wins over the built-in one.
const rank = (candidate: EntryCandidate) => (isBuiltinBackend(candidate.backend) ? 1 : 0);
const best = Math.min(...candidates.map(rank));
const pool = candidates.filter((candidate) => rank(candidate) === best);
const targets = evidence.targets.map((target) => target.name);
return pool.find((candidate) => targets.includes(candidate.agent.name)) ?? pool[0] ?? null;
}
export type EntryGateDeps = {
listAgents: () => Promise<{ ok: boolean; agents: VibeAgentBrief[]; default_agent_name: string | null }>;
getBackendConnection: (backend: AgentBackendId) => Promise<BackendConnectionState>;
agentReads: CollectionReadAuthority<AgentSupply[]>;
getRuntimeStatus: () => Promise<RuntimeDependency>;
getVibeAgent: (
name: string,
params?: { cache?: boolean },
) => Promise<{ ok: boolean; agent: VibeAgentFull; default_agent_name: string | null }>;
detectCli: (binary: string, backend: AssistantId) => Promise<{ status: CliStatus }>;
};
export type EntryReadOptions = {
/** Already-fresh prerequisite body, used only for configured CLI paths. */
config?: Record<string, unknown>;
};
const asSettled = <T>(promise: Promise<T>): Promise<PromiseSettledResult<T>> =>
promise.then(
(value): PromiseSettledResult<T> => ({ status: 'fulfilled', value }),
(reason): PromiseSettledResult<T> => ({ status: 'rejected', reason }),
);
const noneFound = (): Record<AssistantId, boolean> =>
Object.fromEntries(ASSISTANT_ORDER.map((backend) => [backend, false])) as Record<AssistantId, boolean>;
/**
* One round of the fresh reads the gate judges, or `null` when it cannot judge.
*
* `null` is the superseded supply read: a newer generation of the shared authority is
* already in flight, so the list this round would have used is not the current answer
* and holding is the only honest thing to do. It is not a failure — nothing is written
* and nothing is claimed — and the next click reads again.
*
* Hub IPC (`refresh`, `getRuntimeStatus`) is settled independently of application-state
* evidence. A confirmed `stopped` connection must still reach recovery when those reads
* throw `engine_down`. Unread supply or runtime is not an admitted machine: the
* correlated gate still has to pass on a later current read.
*
* A connection that throws is dropped rather than fatal: one unreachable backend is a
* backend that cannot be entered on, not a verdict about the other two.
*/
export async function readEntryEvidence(
deps: EntryGateDeps,
options: EntryReadOptions = {},
): Promise<EntryEvidence | null> {
const [supplyOutcome, runtimeOutcome, connectionResults, agentsOutcome, cliResults] = await Promise.all([
asSettled(deps.agentReads.refresh()),
asSettled(deps.getRuntimeStatus()),
Promise.allSettled(ENTRY_ORDER.map((backend) => deps.getBackendConnection(backend))),
asSettled(deps.listAgents()),
Promise.allSettled(ASSISTANT_ORDER.map(async (backend) => {
const path = configuredCliPath(options.config, backend);
const detected = await deps.detectCli(path, backend);
return { backend, healthy: detected?.status === 'ok' };
})),
]);
if (supplyOutcome.status === 'fulfilled' && supplyOutcome.value.kind === 'stale') return null;
const supplies = supplyOutcome.status === 'fulfilled' && supplyOutcome.value.kind === 'current'
? supplyOutcome.value.value
: null;
const agents = agentsOutcome.status === 'fulfilled'
? agentsOutcome.value
: { ok: false, agents: [] as VibeAgentBrief[], default_agent_name: null };
const listed = agents.ok ? agents.agents : [];
const targets = agents.ok ? await readSetupTargets(listed, deps) : [];
const cliHealthy = noneFound();
for (const result of cliResults) {
if (result.status === 'fulfilled') cliHealthy[result.value.backend] = result.value.healthy;
}
return {
agentsRead: agents.ok,
agents: listed,
defaultAgentName: agents.default_agent_name,
targets,
connections: connectionResults.flatMap((result) =>
result.status === 'fulfilled' && result.value.ok ? [result.value] : []),
suppliesRead: supplies !== null,
supplies: supplies ?? [],
runtime: runtimeOutcome.status === 'fulfilled' ? runtimeOutcome.value : null,
cliHealthy,
};
}