hypervibes 0.0.0-stage → 0.4.0

package/dist/notifications/notification-service.js

@@ -0,0 +1,324 @@
+import { randomUUID } from "node:crypto";
+import { AgentError } from "../agents/agent-input.js";
+import { assertActiveActor, requestHash } from "../memory/operations.js";
+import { chunkText } from "../gateway/handlers.js";
+import { NotificationDeliveryError } from "./delivery.js";
+const columns = `id,agent_id AS agentId,category,title,body,severity,source,subagent_id AS subagentId,run_id AS runId,
+  conversation_id AS conversationId,order_request_id AS orderRequestId,created_at AS createdAt,delivery,attempts,sent_at AS sentAt,error`;
+function input(value) {
+    if (typeof value.title !== "string" || !value.title.trim() || value.title.length > 200)
+        throw new AgentError("Notification title must contain 1–200 characters.");
+    if (typeof value.body !== "string" || !value.body.trim() || value.body.length > 12000)
+        throw new AgentError("Notification body must contain 1–12000 characters.");
+    const severity = value.severity ?? "info";
+    if (!["info", "warning", "error"].includes(severity))
+        throw new AgentError("Invalid notification severity.");
+    return { title: value.title.trim(), body: value.body.trim(), severity };
+}
+/** Application-owned inbox and durable Telegram outbox. Never performs network I/O in a SQL transaction. */
+export class NotificationService {
+    db;
+    origin;
+    logger;
+    clock;
+    sender;
+    stopping = false;
+    started = false;
+    timer;
+    running;
+    closing;
+    shutdown = new AbortController();
+    listeners = new Map();
+    chatNext = new Map();
+    constructor(db, origin, logger, clock = Date.now) {
+        this.db = db;
+        this.origin = origin;
+        this.logger = logger;
+        this.clock = clock;
+    }
+    installSender(sender) { this.sender = sender; }
+    async settingsTx(tx, agentId) {
+        const agent = await tx.get("SELECT created_at,state FROM hv_agents WHERE id=?", agentId);
+        if (!agent)
+            throw new AgentError("Agent not found", 404);
+        await tx.run("INSERT INTO hv_notification_settings(agent_id,enabled_since,fills_since) VALUES (?,?,?) ON CONFLICT DO NOTHING", agentId, agent.created_at, agent.created_at);
+        return (await tx.get("SELECT * FROM hv_notification_settings WHERE agent_id=?", agentId));
+    }
+    async getSettings(agentId) {
+        const row = await this.db.transaction((tx) => this.settingsTx(tx, agentId));
+        return { enabled: Boolean(row.enabled), submissions: Boolean(row.submissions), fills: Boolean(row.fills) };
+    }
+    async saveSettings(agentId, value) {
+        if (!value || typeof value !== "object")
+            throw new AgentError("Invalid notification settings.");
+        const settings = value;
+        if ([settings.enabled, settings.submissions, settings.fills].some((v) => typeof v !== "boolean"))
+            throw new AgentError("Invalid notification settings.");
+        await this.db.transaction(async (tx) => {
+            const previous = await this.settingsTx(tx, agentId), now = this.clock();
+            await tx.run(`UPDATE hv_notification_settings SET enabled=?,submissions=?,fills=?,enabled_since=?,fills_since=? WHERE agent_id=?`, Number(settings.enabled), Number(settings.submissions), Number(settings.fills), settings.enabled && !previous.enabled ? now : previous.enabled_since, settings.fills && !previous.fills ? now : previous.fills_since, agentId);
+            await tx.run(`UPDATE hv_notifications SET delivery='suppressed',error='Notifications disabled before delivery' WHERE agent_id=? AND delivery='pending'
+        AND (?=0 OR (category='submission' AND ?=0) OR (category='fill' AND ?=0))`, agentId, Number(settings.enabled), Number(settings.submissions), Number(settings.fills));
+        });
+        this.changed(agentId);
+        return { enabled: settings.enabled, submissions: settings.submissions, fills: settings.fills };
+    }
+    async queueTx(tx, agentId, eventKey, category, value, provenance) {
+        const existing = await tx.get("SELECT id FROM hv_notifications WHERE agent_id=? AND event_key=?", agentId, eventKey);
+        if (existing)
+            return { status: "queued", id: existing.id };
+        const skipped = await tx.get("SELECT 1 FROM hv_notification_operations WHERE agent_id=? AND operation_key=?", agentId, `skipped:${eventKey}`);
+        if (skipped)
+            return { status: "disabled" };
+        const settings = await this.settingsTx(tx, agentId);
+        if (!settings.enabled || (category === "submission" && !settings.submissions) || (category === "fill" && !settings.fills)) {
+            await tx.run("INSERT INTO hv_notification_operations(agent_id,operation_key,request_hash,result) VALUES (?,?,'',?) ON CONFLICT DO NOTHING", agentId, `skipped:${eventKey}`, JSON.stringify({ status: "disabled" }));
+            return { status: "disabled" };
+        }
+        const agent = await tx.get("SELECT state FROM hv_agents WHERE id=?", agentId);
+        if (!agent || ["stopping", "stopped"].includes(agent.state))
+            return { status: "disabled" };
+        const id = await this.persistTx(tx, agentId, eventKey, category, value, provenance, true);
+        return { status: "queued", id };
+    }
+    async persistTx(tx, agentId, eventKey, category, value, provenance, deliver) {
+        const message = input(value), now = this.clock(), id = randomUUID();
+        const gateway = deliver ? await tx.get("SELECT chat_id,bot_token_hash FROM hv_gateways WHERE agent_id=? AND type='telegram'", agentId) : undefined;
+        const connected = gateway?.chat_id !== null && gateway?.chat_id !== undefined;
+        await tx.run(`INSERT INTO hv_notifications(id,agent_id,event_key,category,title,body,severity,source,subagent_id,run_id,conversation_id,order_request_id,created_at,delivery,chat_id,bot_token_hash,next_attempt_at)
+      VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?)`, id, agentId, eventKey, category, message.title, message.body, message.severity, provenance.source, provenance.subagentId ?? null, provenance.runId ?? null, provenance.conversationId ?? null, provenance.orderRequestId ?? null, now, connected ? "pending" : "web_only", gateway?.chat_id ?? null, connected ? gateway.bot_token_hash : null, now);
+        return id;
+    }
+    /** Always records a system event. The caller must call changed(agentId) after the transaction commits. */
+    async systemWarningTx(tx, agentId, eventKey, value, provenance) {
+        input(value);
+        if (!eventKey.trim() || eventKey.length > 200)
+            throw new AgentError("Invalid notification event key.");
+        const key = `system:${eventKey}`;
+        const existing = await tx.get("SELECT id FROM hv_notifications WHERE agent_id=? AND event_key=?", agentId, key);
+        if (existing)
+            return { id: existing.id, created: false };
+        const settings = await this.settingsTx(tx, agentId);
+        const agent = await tx.get("SELECT state FROM hv_agents WHERE id=?", agentId);
+        const deliver = Boolean(settings.enabled) && !!agent && !["stopping", "stopped"].includes(agent.state);
+        const id = await this.persistTx(tx, agentId, key, "message", value, provenance, deliver);
+        return { id, created: true };
+    }
+    /** Trusted backend entry point. The key identifies one logical application event. */
+    async send(agentId, eventKey, value) {
+        input(value);
+        if (!eventKey.trim() || eventKey.length > 200)
+            throw new AgentError("Invalid notification event key.");
+        const result = await this.db.transaction((tx) => this.queueTx(tx, agentId, `backend:${eventKey}`, "message", value, { source: "Backend" }));
+        this.changed(agentId);
+        return result;
+    }
+    async sendFromTool(actor, value, execution) {
+        const message = input(value), key = `tool:${actor.toolTaskId}`, hash = requestHash(actor, "send_notification", message);
+        const result = await this.db.transaction(async (tx) => {
+            const receipt = await tx.get("SELECT request_hash,result FROM hv_notification_operations WHERE agent_id=? AND operation_key=?", actor.agentId, key);
+            if (receipt) {
+                if (receipt.request_hash !== hash)
+                    throw new AgentError("Notification operation reused with different arguments or actor", 409);
+                return JSON.parse(receipt.result);
+            }
+            if (actor.toolTaskId === null || actor.conversationId === null || !actor.subagentId)
+                throw new AgentError("Unverified notification producer", 403);
+            await assertActiveActor(tx, actor);
+            await execution.authorize(tx, actor, "send_notification");
+            const worker = await tx.get("SELECT name,kind FROM hv_subagents WHERE agent_id=? AND id=?", actor.agentId, actor.subagentId);
+            const result = await this.queueTx(tx, actor.agentId, key, "message", message, { source: worker?.name ?? "Agent", subagentId: actor.subagentId, runId: actor.runId, conversationId: actor.conversationId });
+            await tx.run("INSERT INTO hv_notification_operations(agent_id,operation_key,request_hash,result) VALUES (?,?,?,?)", actor.agentId, key, hash, JSON.stringify(result));
+            return result;
+        });
+        this.changed(actor.agentId);
+        return result;
+    }
+    /** Runs inside the order outcome transaction; one aggregate receipt per request, plus uncertainty resolution. */
+    async orderOutcomeTx(tx, actionId) {
+        const request = await tx.get(`SELECT r.* FROM hv_order_requests r JOIN hv_order_actions a ON a.request_id=r.id WHERE a.id=? AND r.kind IN ('submit','close_position')`, actionId);
+        if (!request)
+            return;
+        const actions = await tx.all("SELECT state FROM hv_order_actions WHERE request_id=?", request.id);
+        const existing = await tx.get("SELECT title FROM hv_notifications WHERE agent_id=? AND event_key=?", request.agent_id, `order:${request.id}:submission`);
+        if (actions.some((a) => a.state === "submitting"))
+            return;
+        // A crash can leave later legs prepared forever. Still warn immediately about
+        // an uncertain attempted leg, without waiting for a model to replay the request.
+        if (actions.some((a) => a.state === "prepared") && !actions.some((a) => a.state === "unknown") && !existing)
+            return;
+        const settings = await this.settingsTx(tx, request.agent_id);
+        if (request.created_at < settings.enabled_since)
+            return;
+        const items = await tx.all(`SELECT i.view FROM hv_order_items i JOIN hv_order_actions a ON a.id=i.action_id WHERE a.request_id=? ORDER BY a.ordinal,i.ordinal`, request.id);
+        const views = items.map((row) => JSON.parse(row.view));
+        const unknown = views.some((v) => v.commandStatus === "unknown");
+        if (existing && (existing.title !== "Order submission outcome unknown" || unknown))
+            return;
+        if (existing && await tx.get("SELECT 1 FROM hv_notifications WHERE agent_id=? AND event_key=?", request.agent_id, `order:${request.id}:resolved`))
+            return;
+        const rejected = views.some((v) => v.commandStatus === "rejected" || v.commandStatus === "not_sent");
+        const accepted = views.some((v) => ["accepted", "reconciled"].includes(v.commandStatus));
+        const title = existing ? "Order submission outcome resolved" : unknown ? "Order submission outcome unknown" : rejected ? accepted ? "Order submission partially accepted" : "Order submission rejected / not sent" : "Orders submitted";
+        const body = [`Request: ${request.request_key}`, ...views.map((v) => `${v.symbol} ${v.side} ${v.kind}: ${v.size ?? "unknown"} @ ${v.triggerPrice ?? v.price ?? "market"} — ${v.commandStatus}${v.exchangeOid ? ` (order ${v.exchangeOid})` : ""}${v.error ? `; ${v.error}` : ""}`), unknown ? "Unknown is not failure. Reconcile this request; do not resubmit with a new ID." : "Submission acceptance is not proof of a fill. Fill notifications report actual executions."].join("\n");
+        const provenance = await tx.get("SELECT producer_subagent_id AS subagent_id,source_run_id,conversation_id FROM hv_order_request_provenance WHERE request_id=?", request.id);
+        const result = await this.queueTx(tx, request.agent_id, `order:${request.id}:${existing ? "resolved" : "submission"}`, "submission", { title, body: body.slice(0, 12000), severity: unknown || (rejected && accepted) ? "warning" : rejected ? "error" : "info" }, { source: "Order execution", subagentId: provenance?.subagent_id, runId: provenance?.source_run_id, conversationId: provenance?.conversation_id, orderRequestId: request.id });
+        return result.status === "queued" ? request.agent_id : undefined;
+    }
+    /** Called only for newly inserted exchange fills, atomically with journal evidence. */
+    async fillsTx(tx, account, events) {
+        const changed = new Set();
+        if (!events.length)
+            return [];
+        const agents = await tx.all("SELECT id FROM hv_agents WHERE trading_account_address=? AND state NOT IN ('stopping','stopped')", account);
+        for (const agent of agents) {
+            const settings = await this.settingsTx(tx, agent.id);
+            if (!settings.enabled || !settings.fills)
+                continue;
+            // Never announce old history imports. The persisted floor survives restarts and re-enabling.
+            const fresh = events.filter((event) => event.time >= Math.max(settings.enabled_since, settings.fills_since));
+            const groups = new Map();
+            for (const event of fresh) {
+                const raw = event.raw;
+                const key = typeof raw?.oid === "number" && Number.isSafeInteger(raw.oid) ? `${event.symbol}:${raw.oid}` : event.id;
+                const group = groups.get(key) ?? [];
+                group.push(event);
+                groups.set(key, group);
+            }
+            for (const group of groups.values()) {
+                group.sort((a, b) => a.time - b.time || a.id.localeCompare(b.id));
+                const event = group[0];
+                const raw = event.raw;
+                const oid = typeof raw?.oid === "number" && Number.isSafeInteger(raw.oid) ? String(raw.oid) : null;
+                const cloid = typeof raw?.cloid === "string" ? raw.cloid : null;
+                const local = oid || cloid ? await tx.get(`SELECT r.id AS request_id,p.producer_subagent_id,p.source_run_id FROM hv_order_items i JOIN hv_order_actions a ON a.id=i.action_id JOIN hv_order_requests r ON r.id=a.request_id LEFT JOIN hv_order_request_provenance p ON p.request_id=r.id WHERE r.agent_id=? AND r.account=? AND (i.oid=? OR i.cloid=?) LIMIT 1`, agent.id, account, oid, cloid) : undefined;
+                const title = `${event.symbol ?? "Account"} order fill${raw?.liquidation ? " (liquidation)" : ""}`;
+                const executions = group.slice(0, 30).map((entry) => {
+                    const data = entry.raw;
+                    const side = entry.fill?.side ?? data?.side, size = entry.fill?.size ?? data?.sz, price = entry.fill?.price ?? data?.px;
+                    return `${side === "B" || side === "buy" ? "Buy" : side === "A" || side === "sell" ? "Sell" : "Unknown side"} ${typeof size === "string" ? size : "unknown quantity"} ${entry.symbol ?? ""} @ ${typeof price === "string" ? price : "unknown price"}`;
+                });
+                const body = `${executions.join("\n")}${group.length > 30 ? `\n${group.length - 30} more executions; see account transaction history.` : ""}\n${group.length > 1 ? `${group.length} executions observed together\n` : ""}${oid ? `Order: ${oid}\n` : ""}Observed: ${new Date(event.time).toISOString()}\nOrigin: ${local ? "HyperVibes order" : "External or unknown (not linked to a HyperVibes order)"}\nThese are executed quantities, not proof that the entire order filled.`;
+                const result = await this.queueTx(tx, agent.id, `fill:${event.id}`, "fill", { title: title.slice(0, 200), body: body.slice(0, 12000), severity: raw?.liquidation ? "warning" : "info" }, { source: local ? "Account fill · HyperVibes" : "Account fill · external/unknown", subagentId: local?.producer_subagent_id, runId: local?.source_run_id, orderRequestId: local?.request_id });
+                if (result.status === "queued")
+                    changed.add(agent.id);
+            }
+        }
+        return [...changed];
+    }
+    async list(agentId, page = 1) {
+        if (!Number.isSafeInteger(page) || page < 1 || page > 100000)
+            throw new AgentError("Invalid notification page.");
+        return this.db.transaction(async (tx) => {
+            const total = (await tx.get("SELECT count(*) AS total FROM hv_notifications WHERE agent_id=?", agentId)).total;
+            const pages = Math.max(1, Math.ceil(total / 50));
+            page = Math.min(page, pages);
+            const items = await tx.all(`SELECT ${columns} FROM hv_notifications WHERE agent_id=? ORDER BY created_at DESC,id DESC LIMIT 50 OFFSET ?`, agentId, (page - 1) * 50);
+            return { items, page, pages, total };
+        });
+    }
+    async get(agentId, id) {
+        const row = await this.db.get(`SELECT ${columns} FROM hv_notifications WHERE agent_id=? AND id=?`, agentId, id);
+        if (!row)
+            throw new AgentError("Notification not found", 404);
+        return row;
+    }
+    /** Called after the owning transaction commits; delivery never waits on a model. */
+    changed(agentId) {
+        for (const listener of this.listeners.get(agentId) ?? [])
+            listener();
+        if (this.started && !this.stopping)
+            this.schedule(0);
+    }
+    async watch(agentId, signal, publish) {
+        let revision = 0, dirty = true, wake;
+        const changed = () => { dirty = true; wake?.(); };
+        const listeners = this.listeners.get(agentId) ?? new Set();
+        listeners.add(changed);
+        this.listeners.set(agentId, listeners);
+        signal.addEventListener("abort", changed);
+        try {
+            while (!signal.aborted) {
+                if (dirty) {
+                    dirty = false;
+                    publish({ revision: revision++ });
+                }
+                await new Promise((resolve) => { wake = resolve; if (dirty || signal.aborted)
+                    resolve(); });
+                wake = undefined;
+            }
+        }
+        finally {
+            listeners.delete(changed);
+            if (!listeners.size)
+                this.listeners.delete(agentId);
+            signal.removeEventListener("abort", changed);
+        }
+    }
+    start() { if (this.started || this.stopping)
+        return; this.started = true; this.schedule(0); }
+    schedule(ms) {
+        clearTimeout(this.timer);
+        this.timer = setTimeout(() => { void this.flush().catch((error) => this.logger?.error(error, "Notification delivery pass failed")).finally(() => { if (!this.stopping)
+            this.schedule(1000); }); }, ms);
+        this.timer.unref();
+    }
+    /** Single-flight delivery pass, also used by isolated tests. */
+    flush() {
+        if (this.stopping)
+            return Promise.resolve();
+        return this.running ??= this.deliver().finally(() => { this.running = undefined; });
+    }
+    async deliver() {
+        if (!this.sender)
+            return;
+        const rows = await this.db.all(`SELECT ${columns},chat_id AS chatId,bot_token_hash AS botTokenHash,message_ids AS messageIds FROM hv_notifications WHERE id IN (
+      SELECT id FROM (SELECT id,row_number() OVER (PARTITION BY bot_token_hash,chat_id ORDER BY created_at,id) AS position
+      FROM hv_notifications WHERE delivery='pending' AND next_attempt_at<=?) WHERE position=1
+    ) ORDER BY created_at,id LIMIT 50`, this.clock());
+        for (const row of rows) {
+            if (this.stopping)
+                return;
+            const chatKey = `${row.botTokenHash}:${row.chatId}`;
+            if ((this.chatNext.get(chatKey) ?? 0) > this.clock())
+                continue;
+            const allowed = await this.db.transaction(async (tx) => {
+                const settings = await this.settingsTx(tx, row.agentId);
+                const current = await tx.get("SELECT delivery FROM hv_notifications WHERE id=?", row.id);
+                if (!current || current.delivery !== "pending")
+                    return false;
+                const gateway = await tx.get("SELECT 1 FROM hv_gateways WHERE agent_id=? AND type='telegram' AND chat_id=? AND bot_token_hash=?", row.agentId, row.chatId, row.botTokenHash);
+                const agent = await tx.get("SELECT state FROM hv_agents WHERE id=?", row.agentId);
+                if (!settings.enabled || (row.category === "submission" && !settings.submissions) || (row.category === "fill" && !settings.fills) || !gateway || !agent || ["stopping", "stopped"].includes(agent.state)) {
+                    await tx.run("UPDATE hv_notifications SET delivery='suppressed',error='Notifications disabled or Telegram destination changed' WHERE id=?", row.id);
+                    return false;
+                }
+                return true;
+            });
+            if (!allowed) {
+                this.changed(row.agentId);
+                continue;
+            }
+            const emoji = row.severity === "error" ? "❌" : row.severity === "warning" ? "⚠️" : "ℹ️";
+            const chunks = chunkText(`${emoji} ${row.title}\n\n${row.body}\n\n${new URL(`/agents/${encodeURIComponent(row.agentId)}/notifications/${row.id}`, this.origin).href}`, 4000);
+            const ids = JSON.parse(row.messageIds);
+            try {
+                const messageId = await this.sender({ agentId: row.agentId, chatId: row.chatId, botTokenHash: row.botTokenHash }, chunks[ids.length], this.shutdown.signal);
+                ids.push(messageId);
+                await this.db.run(`UPDATE hv_notifications SET message_ids=?,delivery=CASE WHEN ?=1 THEN 'sent' ELSE delivery END,sent_at=?,error=NULL,next_attempt_at=? WHERE id=?`, JSON.stringify(ids), ids.length === chunks.length ? 1 : 0, ids.length === chunks.length ? this.clock() : null, this.clock() + 1100, row.id);
+                this.chatNext.set(chatKey, this.clock() + 1100);
+            }
+            catch (error) {
+                if (this.stopping)
+                    return; // Interrupted sends remain recoverable; Telegram has no idempotency key.
+                const detail = error instanceof NotificationDeliveryError ? error : new NotificationDeliveryError("Telegram delivery failed; retrying");
+                const attempts = row.attempts + 1;
+                const delay = Math.max(detail.retryAfterMs ?? 0, Math.min(900000, 1000 * 2 ** attempts));
+                await this.db.run("UPDATE hv_notifications SET attempts=?,delivery=?,error=?,next_attempt_at=? WHERE id=? AND delivery='pending'", attempts, detail.suppressed ? "suppressed" : detail.permanent || attempts >= 8 ? "failed" : "pending", detail.message, this.clock() + delay, row.id);
+                this.chatNext.set(chatKey, this.clock() + delay);
+            }
+            this.changed(row.agentId);
+        }
+    }
+    close() { return this.closing ??= (async () => { this.stopping = true; clearTimeout(this.timer); this.shutdown.abort(); await this.running; this.chatNext.clear(); })(); }
+}

package/dist/providers/credential-store.js

@@ -0,0 +1,86 @@
+import { and, eq } from "drizzle-orm";
+import { hvProviderConnections } from "../db/provider-schema.js";
+import { decryptSecret, encryptSecret } from "../hyperliquid/crypto.js";
+import { AgentError } from "../agents/agent-input.js";
+/** One instance per user, shared by all of that user's harnesses. */
+export class SqliteCredentials {
+    db;
+    userId;
+    key;
+    pending = new Map();
+    constructor(db, userId, key) {
+        this.db = db;
+        this.userId = userId;
+        this.key = key;
+    }
+    where(providerId) {
+        return and(eq(hvProviderConnections.userId, this.userId), eq(hvProviderConnections.providerId, providerId));
+    }
+    requireKey() {
+        if (!this.key)
+            throw new AgentError("Provider connections require AGENTS_ENCRYPTION_KEY on the server.", 503);
+        return this.key;
+    }
+    serialize(id, operation) {
+        const result = (this.pending.get(id) ?? Promise.resolve()).then(operation);
+        const settled = result.then(() => { }, () => { });
+        this.pending.set(id, settled);
+        void settled.then(() => { if (this.pending.get(id) === settled)
+            this.pending.delete(id); });
+        return result;
+    }
+    async read(providerId, options) {
+        options?.signal?.throwIfAborted();
+        const row = await this.db.select().from(hvProviderConnections).where(this.where(providerId)).get();
+        if (!row)
+            return undefined;
+        const key = this.requireKey();
+        if (row.keyId !== key.id)
+            throw new Error("Provider encryption key is unavailable");
+        const payload = JSON.parse(decryptSecret(key, row.ciphertext));
+        if (payload.userId !== this.userId || payload.providerId !== providerId || payload.credential?.type !== row.authType) {
+            throw new Error("Provider credential identity mismatch");
+        }
+        return payload.credential;
+    }
+    async list(options) {
+        options?.signal?.throwIfAborted();
+        return this.db.select({ providerId: hvProviderConnections.providerId, type: hvProviderConnections.authType })
+            .from(hvProviderConnections).where(eq(hvProviderConnections.userId, this.userId)).all();
+    }
+    modify(providerId, fn, options) {
+        return this.serialize(providerId, async () => {
+            options?.signal?.throwIfAborted();
+            const current = await this.read(providerId, options);
+            // OAuth refresh may use the network here. Hold only the per-provider
+            // mutex, NEVER the shared SQLite queue/transaction across this callback.
+            const next = await fn(current);
+            if (next === undefined)
+                return current;
+            const key = this.requireKey();
+            const values = { authType: next.type, ciphertext: Buffer.from(encryptSecret(key, JSON.stringify({ userId: this.userId, providerId, credential: next }))), keyId: key.id, updatedAt: Date.now() };
+            await this.db.insert(hvProviderConnections).values({ userId: this.userId, providerId, ...values })
+                .onConflictDoUpdate({ target: [hvProviderConnections.userId, hvProviderConnections.providerId], set: values }).run();
+            return next;
+        });
+    }
+    delete(providerId, options) {
+        return this.serialize(providerId, async () => {
+            options?.signal?.throwIfAborted();
+            await this.db.delete(hvProviderConnections).where(this.where(providerId)).run();
+        });
+    }
+    catalogStore() {
+        return {
+            read: async (id) => {
+                const row = await this.db.select({ catalog: hvProviderConnections.catalog }).from(hvProviderConnections).where(this.where(id)).get();
+                return row?.catalog ? JSON.parse(row.catalog) : undefined;
+            },
+            write: async (id, entry) => {
+                await this.db.update(hvProviderConnections).set({ catalog: JSON.stringify(entry) }).where(this.where(id)).run();
+            },
+            delete: async (id) => { await this.db.update(hvProviderConnections).set({ catalog: null }).where(this.where(id)).run(); },
+        };
+    }
+    async drain() { await Promise.all(this.pending.values()); }
+}

package/dist/providers/ollama-cloud.js

@@ -0,0 +1,148 @@
+import { envApiKeyAuth } from "@earendil-works/pi-ai";
+import { openAICompletionsApi } from "@earendil-works/pi-ai/api/openai-completions.lazy";
+import { createProvider } from "@earendil-works/pi-ai/models";
+/** Ollama Cloud (https://ollama.com) is an OpenAI-compatible API with a purely
+ * dynamic catalog: no model list ships with the app. The catalog is fetched
+ * live per user, once that user has connected an API key. */
+const PROVIDER_ID = "ollama-cloud";
+const CLOUD_BASE = "https://ollama.com";
+const API_BASE = `${CLOUD_BASE}/v1`;
+const FETCH_TIMEOUT_MS = 10_000;
+const SHOW_CONCURRENCY = 8;
+const DEFAULT_CONTEXT_WINDOW = 128_000;
+// /api/show does not expose an output limit; this matches Ollama Cloud's
+// observed cap for the largest responses.
+const DEFAULT_MAX_TOKENS = 32_768;
+/** Compat overrides for ollama.com. pi-ai detects generic-OpenAI defaults from
+ * the base URL, which are wrong for Ollama (developer role, store field,
+ * max_completion_tokens, prompt cache retention). */
+const compat = {
+    // Ollama serves "system" messages, not the "developer" role.
+    supportsDeveloperRole: false,
+    supportsStore: false,
+    maxTokensField: "max_tokens",
+    supportsReasoningEffort: true,
+    supportsUsageInStreaming: true,
+    thinkingFormat: "openai",
+    sendSessionAffinityHeaders: false,
+    supportsLongCacheRetention: false,
+};
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function authHeaders(credential) {
+    return credential?.type === "api_key" && credential.key ? { Authorization: `Bearer ${credential.key}` } : {};
+}
+async function fetchJson(url, init, signal) {
+    const response = await fetch(url, { ...init, signal: AbortSignal.any([signal, AbortSignal.timeout(FETCH_TIMEOUT_MS)]) });
+    if (!response.ok) {
+        if (response.status === 429)
+            throw new Error("Ollama Cloud rate limited the request. Try again shortly.");
+        throw new Error(`Ollama Cloud request to ${new URL(url).pathname} failed: ${response.status}`);
+    }
+    try {
+        return await response.json();
+    }
+    catch {
+        throw new Error(`Ollama Cloud returned invalid JSON from ${new URL(url).pathname}`);
+    }
+}
+async function fetchModelIds(credential, signal) {
+    const body = await fetchJson(`${API_BASE}/models`, { headers: authHeaders(credential) }, signal);
+    if (!isRecord(body) || !Array.isArray(body.data))
+        throw new Error("Ollama Cloud model list has an unexpected shape.");
+    const ids = [];
+    for (const entry of body.data) {
+        if (!isRecord(entry) || typeof entry.id !== "string" || !entry.id.trim()) {
+            throw new Error("Ollama Cloud model list has an unexpected shape.");
+        }
+        ids.push(entry.id);
+    }
+    return ids;
+}
+async function fetchModelDetails(id, credential, signal) {
+    const body = await fetchJson(`${CLOUD_BASE}/api/show`, {
+        method: "POST",
+        headers: { ...authHeaders(credential), "Content-Type": "application/json" },
+        body: JSON.stringify({ model: id }),
+    }, signal);
+    if (!isRecord(body) || !Array.isArray(body.capabilities) || !body.capabilities.every((capability) => typeof capability === "string")) {
+        throw new Error(`Ollama Cloud returned invalid details for ${id}.`);
+    }
+    return { capabilities: body.capabilities, modelInfo: isRecord(body.model_info) ? body.model_info : {} };
+}
+/** /api/show reports context lengths as `<family>.context_length` keys. */
+function contextLength(modelInfo) {
+    for (const [key, value] of Object.entries(modelInfo)) {
+        if (key.endsWith(".context_length") && typeof value === "number" && Number.isInteger(value) && value > 0)
+            return value;
+    }
+    return DEFAULT_CONTEXT_WINDOW;
+}
+function assembleModel(id, details) {
+    return {
+        id,
+        name: id,
+        provider: PROVIDER_ID,
+        api: "openai-completions",
+        baseUrl: API_BASE,
+        input: details.capabilities.includes("vision") ? ["text", "image"] : ["text"],
+        reasoning: details.capabilities.includes("thinking"),
+        // Ollama Cloud is subscription-billed; zero rates keep usage accounting
+        // from inventing pay-as-you-go charges that do not apply.
+        cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+        contextWindow: contextLength(details.modelInfo),
+        maxTokens: DEFAULT_MAX_TOKENS,
+        compat,
+    };
+}
+/** Fetch the live catalog with the user's credential. Throws on total or
+ * partial failure so the caller keeps the previous catalog instead of
+ * persisting an incomplete one. Agents need tool support, so models without
+ * the "tools" capability are dropped; an empty remainder is an error. */
+export async function fetchModels(context) {
+    const credential = context.credential;
+    const ids = await fetchModelIds(credential, context.signal);
+    if (context.signal.aborted)
+        return [];
+    const details = new Map();
+    const failures = [];
+    let next = 0;
+    await Promise.all(Array.from({ length: Math.min(SHOW_CONCURRENCY, ids.length) }, async () => {
+        while (next < ids.length) {
+            const id = ids[next++];
+            try {
+                details.set(id, await fetchModelDetails(id, credential, context.signal));
+            }
+            catch (error) {
+                if (context.signal.aborted)
+                    return;
+                failures.push(error instanceof Error ? error.message : String(error));
+            }
+        }
+    }));
+    if (context.signal.aborted)
+        return [];
+    if (failures.length) {
+        throw new Error(`Ollama Cloud catalog refresh incomplete: ${failures.length} of ${ids.length} model(s) failed (${failures[0]})`);
+    }
+    const models = [...details].filter(([, shown]) => shown.capabilities.includes("tools"))
+        .map(([id, shown]) => assembleModel(id, shown));
+    if (!models.length)
+        throw new Error("Ollama Cloud catalog contains no models with tool support");
+    return models;
+}
+/** The Ollama Cloud provider. Its catalog starts empty and is populated from
+ * ollama.com on refresh with the user's stored API key. */
+export function ollamaCloudProvider() {
+    return createProvider({
+        id: PROVIDER_ID,
+        name: "Ollama Cloud",
+        baseUrl: API_BASE,
+        // No ambient server credential: only a per-user stored key resolves.
+        auth: { apiKey: envApiKeyAuth("Ollama Cloud API key", []) },
+        models: [],
+        api: openAICompletionsApi(),
+        fetchModels,
+    });
+}

package/dist/providers/provider-logo-url.js

@@ -0,0 +1,18 @@
+/** Provider ids are URL path segments into /model-catalog/logos and upstream models.dev. */
+export function isProviderSlug(provider) {
+    return provider.length <= 64 && /^[A-Za-z0-9][A-Za-z0-9_-]*$/.test(provider);
+}
+/** Provider ids that don't match their models.dev logo slug get remapped here. */
+const logoSlugAliases = {
+    // models.dev has no Codex logo; the OpenAI knot is the closest match.
+    "openai-codex": "openai",
+    // models.dev catalogs Ollama under its own slug.
+    "ollama-cloud": "ollama",
+};
+export function providerLogoSlug(provider) {
+    return isProviderSlug(provider) ? logoSlugAliases[provider] ?? provider : null;
+}
+export function providerLogoUrl(provider) {
+    const slug = providerLogoSlug(provider);
+    return slug ? `/model-catalog/logos/${encodeURIComponent(slug)}.svg` : null;
+}

package/dist/providers/provider-logo.js

@@ -0,0 +1,31 @@
+import { SvgLogoCache } from "../cache/svg-logo-cache.js";
+import { isProviderSlug, providerLogoSlug } from "./provider-logo-url.js";
+export { isProviderSlug, providerLogoUrl } from "./provider-logo-url.js";
+export function fallbackProviderLogo(provider) {
+    // Only validated provider ids may reach the SVG template.
+    if (!isProviderSlug(provider))
+        throw new Error("Invalid provider id");
+    const initial = provider[0].toUpperCase();
+    return Buffer.from(`<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 32 32" role="img" aria-label="${provider}"><rect width="32" height="32" rx="8" fill="#18181b"/><text x="16" y="21" text-anchor="middle" font-family="ui-sans-serif,system-ui" font-size="14" fill="#fafafa">${initial}</text></svg>`);
+}
+const source = {
+    directory: "model-catalog/logos",
+    validate: isProviderSlug,
+    url: (slug) => `https://models.dev/logos/${slug}.svg`,
+    fallback: fallbackProviderLogo,
+};
+/** Caches models.dev provider logos; see {@link SvgLogoCache} for mechanics. */
+export class ProviderLogoCache {
+    cache;
+    constructor(root, fetcher = fetch) {
+        this.cache = new SvgLogoCache(root, source, fetcher);
+    }
+    get(provider) {
+        // Aliases resolve before caching so each models.dev slug owns one disk entry.
+        const slug = providerLogoSlug(provider);
+        return slug ? this.cache.get(slug) : Promise.reject(new Error("Invalid logo key"));
+    }
+    close() {
+        return this.cache.close();
+    }
+}