export type Json = | null | boolean | number | string | Json[] | { [key: string]: Json }; export type Row = Record; export type HermesErrorCode = | 'CONFIGURATION' | 'AUTH_REQUIRED' | 'UNAVAILABLE' | 'CONTRACT' | 'LIMIT' | 'FORBIDDEN' | 'UNSUPPORTED'; export class HermesError extends Error { constructor(readonly code: HermesErrorCode) { super(`Hermes ${code.toLowerCase()}`); } } export interface HermesConfig { origin: string; token: () => Promise; } export interface Health { ok: boolean; version: string; commit: string; auth_required: boolean; } function object(value: unknown): Record { if (!value || typeof value !== 'object' || Array.isArray(value)) throw new HermesError('CONTRACT'); return value as Record; } function fields( value: unknown, schema: Record, ): Row { const source = object(value); const result: Row = {}; for (const [key, type] of Object.entries(schema)) { if ( typeof source[key] !== type || (type === 'number' && !Number.isFinite(source[key])) ) throw new HermesError('CONTRACT'); result[key] = source[key] as Json; } return result; } export class HermesAdapter { private readonly origin: string; private inflight = 0; constructor( private readonly config: HermesConfig, private readonly fetcher: typeof fetch = fetch, ) { if (config.origin !== 'http://canina-hermes:9119') throw new HermesError('CONFIGURATION'); this.origin = config.origin; } private async request( path: string, profile?: string, method = 'GET', params: Record = {}, ): Promise { if ( profile !== undefined && !/^[a-zA-Z0-9][a-zA-Z0-9_-]{0,63}$/.test(profile) ) throw new HermesError('FORBIDDEN'); const url = new URL(path, this.origin); if (profile) url.searchParams.set('profile', profile); for (const [k, v] of Object.entries(params)) url.searchParams.set(k, v); if (this.inflight >= 4) throw new HermesError('LIMIT'); this.inflight++; const controller = new AbortController(); const timer = setTimeout(() => controller.abort(), 5000); try { const token = await Promise.race([ this.config.token(), new Promise((_, reject) => controller.signal.addEventListener( 'abort', () => reject(new HermesError('UNAVAILABLE')), { once: true }, ), ), ]); if (!token || /[\r\n]/.test(token)) throw new HermesError('AUTH_REQUIRED'); const response = await this.fetcher(url, { method, headers: { Authorization: `Bearer ${token}`, Accept: 'application/json', }, signal: controller.signal, redirect: 'error', }); if ([401, 403].includes(response.status)) throw new HermesError('AUTH_REQUIRED'); if (response.status === 404) throw new HermesError('UNSUPPORTED'); if (!response.ok) throw new HermesError('UNAVAILABLE'); if (Number(response.headers.get('content-length')) > 262144) throw new HermesError('LIMIT'); const reader = response.body?.getReader(); if (!reader) throw new HermesError('CONTRACT'); let bytes = 0; const chunks: Uint8Array[] = []; try { for (;;) { const { done, value } = await reader.read(); if (done) break; bytes += value.byteLength; if (bytes > 262144) throw new HermesError('LIMIT'); chunks.push(value); } } finally { await reader.cancel().catch(() => undefined); } return JSON.parse(Buffer.concat(chunks).toString('utf8')) as unknown; } catch (error) { if (error instanceof HermesError) throw error; throw new HermesError('UNAVAILABLE'); } finally { clearTimeout(timer); this.inflight--; } } async health(): Promise { return fields(await this.request('/api/health'), { ok: 'boolean', version: 'string', commit: 'string', auth_required: 'boolean', }) as unknown as Health; } async status(profile: string): Promise { const raw = object(await this.request('/api/status', profile)); const row = fields(raw, { version: 'string', gateway_running: 'boolean', overall: 'string', active_agents: 'number', }); if (raw.gateway_state !== null && typeof raw.gateway_state !== 'string') throw new HermesError('CONTRACT'); return { ...row, gateway_state: raw.gateway_state as Json }; } async profiles(): Promise { return list(object(await this.request('/api/profiles')).profiles).map((r) => fields(r, { name: 'string', is_default: 'boolean', gateway_running: 'boolean', }), ); } async modelInfo(profile: string): Promise { return fields(await this.request('/api/model/info', profile), { model: 'string', provider: 'string', effective_context_length: 'number', }); } async modelOptions(profile: string): Promise { return list( object(await this.request('/api/model/options', profile)).providers, ).map((r) => { const row = fields(r, { slug: 'string', name: 'string' }); const models = list(object(r).models); if (models.some((m) => typeof m !== 'string')) throw new HermesError('CONTRACT'); return { ...row, models: models as string[] }; }); } async usage(profile: string, days = 30): Promise { bound(days, 1, 365); const raw = object( await this.request('/api/analytics/usage', profile, 'GET', { days: String(days), }), ); return { ...fields(raw, { period_days: 'number' }), totals: fields(raw.totals, { total_input: 'number', total_output: 'number', total_sessions: 'number', total_estimated_cost: 'number', }), }; } async sessions(profile: string, limit = 20, offset = 0): Promise { bound(limit, 1, 100); bound(offset, 0, 10000); const raw = object( await this.request('/api/sessions', profile, 'GET', { limit: String(limit), offset: String(offset), full: 'false', order: 'recent', }), ); if (raw.storage && Object.keys(object(raw.storage)).length) throw new HermesError('UNAVAILABLE'); const rows = list(raw.sessions).map((r) => scoped(r, profile, { id: 'string', profile: 'string', source: 'string', is_active: 'boolean', }), ); return { ...fields(raw, { total: 'number' }), sessions: rows }; } async crons(profile: string): Promise { return list(await this.request('/api/cron/jobs', profile)).map((r) => scoped(r, profile, { id: 'string', profile: 'string', enabled: 'boolean', }), ); } private async cron( profile: string, id: string, action: 'pause' | 'resume', ): Promise { if (!/^[a-zA-Z0-9_-]{1,128}$/.test(id)) throw new HermesError('FORBIDDEN'); return scoped( await this.request(`/api/cron/jobs/${id}/${action}`, profile, 'POST'), profile, { id: 'string', profile: 'string', enabled: 'boolean' }, ); } pauseCron(profile: string, id: string): Promise { return this.cron(profile, id, 'pause'); } resumeCron(profile: string, id: string): Promise { return this.cron(profile, id, 'resume'); } } function list(value: unknown): unknown[] { if (!Array.isArray(value) || value.length > 1000) throw new HermesError('CONTRACT'); return value; } function bound(value: number, min: number, max: number): void { if (!Number.isInteger(value) || value < min || value > max) throw new HermesError('LIMIT'); } function scoped( value: unknown, profile: string, schema: Record, ): Row { const row = fields(value, schema); if (row.profile !== profile) throw new HermesError('FORBIDDEN'); return row; }