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
// The catalog half of the registered mirror: what this client promises to send,
// and what it promises not to drop on the way in.
//
// Two anchors, on purpose. Where `docs/plans/model-hub-contracts/` states a
// shape, the schema is the authority and these tests read it — a field added
// there fails here rather than reaching a projection nobody renders. Where it
// does not, the property is the anchor instead: the real client is driven over
// a stubbed wire, and a typed fixture with no optional field left out is
// asserted to survive the round trip intact.
//
// The candidates read moved from the second anchor to the first when #1837
// merged its authority files, so `ModelCandidate` is now read out of
// `api-response.schema.json` rather than described here twice.
import { readFileSync } from 'node:fs';
import { dirname, resolve } from 'node:path';
import { fileURLToPath } from 'node:url';
import { afterEach, describe, expect, it, vi } from 'vitest';
import { apiFailure, CANDIDATE_ORIGINS, modelsApi } from './modelsApi';
import {
BACKEND_MODEL_INPUT_MODALITIES,
BACKEND_MODEL_OUTPUT_MODALITIES,
CONTRACT_VERSION,
type BackendModel,
type BackendModelsPut,
type ModelCandidate,
type ModelsDevMatch,
type RouteHopRef,
} from './types';
const contract = (name: string): Record<string, never> =>
JSON.parse(
readFileSync(
resolve(dirname(fileURLToPath(import.meta.url)), '../../../../..', 'docs/plans/model-hub-contracts', name),
'utf8',
),
);
/**
* One canned answer, and a record of the request that asked for it.
*
* The subject is the shipped client, not a second mapper written here: a double
* that re-states the projection would agree with itself no matter what the real
* one does with a field.
*/
const stubFetch = (status: number, body: unknown) => {
const fetchMock = vi.fn(async (_input: RequestInfo | URL, _init?: RequestInit) => new Response(
JSON.stringify(body),
{ status, headers: { 'Content-Type': 'application/json' } },
));
vi.stubGlobal('document', { cookie: 'vibe_csrf_token=test-token' });
vi.stubGlobal('fetch', fetchMock);
return fetchMock;
};
const MODEL: BackendModel = {
id: 'anthropic/claude-opus-4-6',
display_name: 'Claude Opus 4.6',
origin: 'models_dev',
models_dev_id: 'anthropic/claude-opus-4-6',
context_window: 200_000,
max_output_tokens: 64_000,
input_modalities: [...BACKEND_MODEL_INPUT_MODALITIES],
output_modalities: [...BACKEND_MODEL_OUTPUT_MODALITIES],
supports_tools: true,
supports_reasoning: null,
reasoning_efforts: ['low', 'high'],
locked: false,
routeable: true,
};
const HOP_REF: RouteHopRef = {
backend: 'opencode',
menu_model: 'glm-5.2',
source_id: 'src_relay0001',
model_id: 'glm-5.2-air',
position: 2,
};
/** Every field the projection states, optional one included — so the schema's
* closed-object set equality below is a relation in both directions. */
const CANDIDATE: Required<ModelCandidate> = {
id: 'glm-5.2',
display_name: 'GLM 5.2',
reasoning_efforts: ['low', 'high'],
suppliers: [{ source_id: 'src_relay0001', source_name: 'relay.example', model_id: 'glm-5.2-air' }],
origin: 'provider',
group_if_removed: 'providers',
native_protocol: 'openai_responses',
models_dev_id: 'zhipuai/glm-5.2',
context_window: 128_000,
max_output_tokens: null,
input_modalities: ['text', 'image'],
output_modalities: ['text'],
supports_tools: true,
supports_reasoning: null,
};
/** The fields an exact models.dev match adds to a provider candidate. */
const MODELS_DEV_FIELDS = [
'models_dev_id', 'context_window', 'max_output_tokens', 'input_modalities',
'output_modalities', 'supports_tools', 'supports_reasoning',
];
const MATCH: ModelsDevMatch = {
provider_id: 'zhipuai',
provider_name: 'Zhipu AI',
model_id: 'glm-5.2',
models_dev_id: 'zhipuai/glm-5.2',
display_name: 'GLM 5.2',
context_window: 128_000,
max_output_tokens: 8_192,
input_modalities: ['text', 'image'],
output_modalities: ['text'],
supports_tools: true,
supports_reasoning: null,
reasoning_efforts: ['low'],
native_protocol: 'openai_responses',
first_party: true,
};
/** A save that removes a routed row AND adds a candidate: every optional field
* of the write is present at once, so nothing can pass by being absent. */
const PUT: BackendModelsPut = {
baseline: [MODEL],
models: [MODEL, { ...MODEL, id: 'glm-5.2', models_dev_id: null, origin: 'manual' }],
force: true,
would_remove_hops: [HOP_REF],
would_interrupt: [{ backend: 'opencode', model_id: 'glm-5.2', agents: ['pm'] }],
expected_suppliers: { 'glm-5.2': [{ source_id: 'src_relay0001', model_id: 'glm-5.2-air' }] },
};
afterEach(() => {
vi.unstubAllGlobals();
});
describe('backend model catalog contract', () => {
it('mirrors every field and vocabulary backend-model.schema.json states', () => {
const schema = contract('backend-model.schema.json') as unknown as {
required: string[];
additionalProperties: boolean;
properties: Record<string, { enum?: string[]; items?: { enum: string[] } }>;
};
// The schema closes its object and requires every property, so set equality
// is the whole relation in both directions: a field it gains is missing
// here, and one this mirror invents is not in it.
expect(schema.additionalProperties).toBe(false);
expect(new Set(Object.keys(MODEL))).toEqual(new Set(schema.required));
// One row carrying every stated modality, so a member added to either
// vocabulary fails to typecheck against the mirror's own constant.
expect(new Set(MODEL.input_modalities)).toEqual(new Set(schema.properties.input_modalities.items?.enum));
expect(new Set(MODEL.output_modalities)).toEqual(new Set(schema.properties.output_modalities.items?.enum));
// The origin vocabulary, both directions now that `provider` has landed in
// the schema: the runtime set the candidates read validates against is the
// one the contract states, so a creation path either side gains fails here
// instead of being read as the group's fallback.
expect(new Set(CANDIDATE_ORIGINS)).toEqual(new Set(schema.properties.origin.enum));
expect(new Set(CANDIDATE_ORIGINS)).toContain(MODEL.origin);
});
it('mirrors the candidate projection api-response.schema.json now states', () => {
const schema = contract('api-response.schema.json') as unknown as {
definitions: {
ModelCandidate: {
required: string[];
additionalProperties: boolean;
properties: Record<string, { anyOf?: { enum?: string[] }[] }>;
};
AddableModelCandidate: { allOf: [unknown, { not: { required: string[] } }] };
AgentModelCandidatesResponse: { properties: { contract_version: { const: number } } };
};
};
const candidate = schema.definitions.ModelCandidate;
// The object is closed, so set equality over the fixture's keys is the
// whole relation: a property the schema gains is missing from the mirror,
// and one the mirror invents is not in the schema. `Required<…>` is what
// makes the optional field participate.
expect(candidate.additionalProperties).toBe(false);
expect(new Set(Object.keys(CANDIDATE)))
.toEqual(new Set([...candidate.required, ...Object.keys(candidate.properties)]));
// And what the mirror calls optional is what the schema leaves out of
// `required`, rather than a second opinion about the same field.
expect(new Set(candidate.required))
.toEqual(new Set(Object.keys(CANDIDATE).filter(
(field) => !['group_if_removed', 'native_protocol', ...MODELS_DEV_FIELDS].includes(field),
)));
// The re-entry vocabulary, and the reason it is a separate field: the schema
// forbids it on the two addable groups, because a candidate not in the list
// has no way back to state.
expect(new Set(candidate.properties.group_if_removed?.anyOf?.[0]?.enum))
.toEqual(new Set(['builtin', 'providers']));
expect(schema.definitions.AddableModelCandidate.allOf[1].not.required).toEqual(['group_if_removed']);
expect(CONTRACT_VERSION).toBe(schema.definitions.AgentModelCandidatesResponse.properties.contract_version.const);
});
it('mirrors the plan hop reference and the version the refusal schema registers', () => {
const schema = contract('guard-refusal.schema.json') as unknown as {
properties: { contract_version: { const: number } };
definitions: { RouteHopRef: { required: string[]; additionalProperties: boolean } };
};
const hopRef = schema.definitions.RouteHopRef;
expect(hopRef.additionalProperties).toBe(false);
expect(new Set(Object.keys(HOP_REF))).toEqual(new Set(hopRef.required));
expect(CONTRACT_VERSION).toBe(schema.properties.contract_version.const);
});
it('hands the picker each candidate group whole, from the registered path', async () => {
const groups = {
builtin: [{ ...CANDIDATE, id: 'gpt-6-codex', origin: 'builtin' as const, suppliers: [] }],
providers: [CANDIDATE],
in_list: [{ ...CANDIDATE, id: 'kimi-k3', origin: 'manual' as const }],
};
const fetchMock = stubFetch(200, { ok: true, contract_version: CONTRACT_VERSION, candidates: groups });
const read = await modelsApi.getAgentModelCandidates('opencode');
expect(fetchMock.mock.calls[0]?.[0]).toBe('/api/models/agents/opencode/models/candidates');
// Deep equality against typed fixtures is the property, and the schema case
// above is what keeps the fixtures honest: every field the contract states
// is on `CANDIDATE`, so a field the projection gains is asserted to survive
// the read rather than being dropped on the way in.
expect(read).toEqual(groups);
});
it('keeps every models.dev field the ranking is stated in', async () => {
stubFetch(200, { ok: true, contract_version: CONTRACT_VERSION, matches: [MATCH] });
const [read] = await modelsApi.searchModelsDev('glm');
expect(read).toEqual(MATCH);
// `first_party` is optional in the mirror — a server that predates it leaves
// the ranking to the order it served — so its survival is asserted rather
// than inferred from a fixture that could have omitted it.
expect(read?.first_party).toBe(true);
});
it('sends the guarded tail and the displayed suppliers verbatim', async () => {
const fetchMock = stubFetch(200, { ok: true, contract_version: CONTRACT_VERSION, agent: { backend: 'opencode' } });
await modelsApi.putAgentModels('opencode', PUT);
const [path, init] = fetchMock.mock.calls[0] ?? [];
expect(path).toBe('/api/models/agents/opencode/models');
expect(init?.method).toBe('PUT');
// The server stores this request literally, so the client's only correct
// transformation of the body is none.
expect(JSON.parse(String(init?.body))).toEqual(PUT);
});
it('projects a stale-candidate refusal and a guarded plan as different answers', async () => {
const refusal = async (body: unknown) => {
stubFetch(409, body);
const failure = await modelsApi.putAgentModels('opencode', PUT).then(
() => null,
(error: unknown) => apiFailure(error),
);
expect(failure, 'a 409 must reject as one of ours').not.toBeNull();
return failure as NonNullable<typeof failure>;
};
const changed = { 'glm-5.2': [{ source_id: 'src_relay0002', model_id: 'glm-5.2' }] };
const stale = await refusal({
ok: false,
contract_version: CONTRACT_VERSION,
error: 'candidate_suppliers_changed',
// Registered on this shape too, because it is a `ModelHubError` like any
// other. The copy it keys is the backend lane's, but the projection that
// has to carry it here is this client's.
detail: 'candidate_suppliers_changed.detail',
changed,
});
// Each refusal is answerable from its own field alone. That is what lets the
// picker refresh its chips and re-ask on one and echo a plan back on the
// other, without reading the code to decide which arrays to trust.
expect(stale.code).toBe('candidate_suppliers_changed');
expect(stale.detail).toBe('candidate_suppliers_changed.detail');
expect(stale.changedSuppliers).toEqual(changed);
expect(stale.wouldRemoveHops).toEqual([]);
expect(stale.serverNamed).toBe(true);
const guarded = await refusal({
ok: false,
contract_version: CONTRACT_VERSION,
error: 'backend_model_in_route',
would_remove_hops: [HOP_REF],
would_interrupt: [{ backend: 'opencode', model_id: 'glm-5.2', agents: ['pm'] }],
});
expect(guarded.code).toBe('backend_model_in_route');
expect(guarded.wouldRemoveHops).toEqual([HOP_REF]);
expect(guarded.wouldInterrupt).toHaveLength(1);
expect(guarded.changedSuppliers).toEqual({});
});
});