hypervibes 0.0.0-stage → 0.4.0

package/dist/providers/provider-service.js

@@ -0,0 +1,295 @@
+import { envApiKeyAuth } from "@earendil-works/pi-ai";
+import { createModels, getSupportedThinkingLevels } from "@earendil-works/pi-ai/models";
+import { builtinProviders } from "@earendil-works/pi-ai/providers/all";
+import { randomUUID } from "node:crypto";
+import { AgentError } from "../agents/agent-input.js";
+import { hvInstallation } from "../db/provider-schema.js";
+import { SqliteCredentials } from "./credential-store.js";
+import { ollamaCloudProvider } from "./ollama-cloud.js";
+/** Every provider a user can connect, with their own live-refreshed catalog. */
+const defaultProviders = () => [...builtinProviders(), ollamaCloudProvider()];
+/** App-owned credentials/catalogs. No ambient server credentials or files are
+ * inherited by a user's collection. A provider connection belongs to that user. */
+export class ProviderService {
+    db;
+    key;
+    options;
+    users = new Map();
+    attempts = new Map();
+    stopping = false;
+    shutdown = new AbortController();
+    deviceId = "";
+    onChanged = async () => { };
+    constructor(db, key, options = {}) {
+        this.db = db;
+        this.key = key;
+        this.options = options;
+    }
+    async initialize() {
+        await this.db.insert(hvInstallation).values({ id: 1, deviceId: randomUUID() }).onConflictDoNothing().run();
+        this.deviceId = (await this.db.select().from(hvInstallation).get()).deviceId;
+    }
+    admit() { if (this.stopping)
+        throw new AgentError("Provider service is shutting down", 503); }
+    user(userId) {
+        this.admit();
+        let pending = this.users.get(userId);
+        if (!pending) {
+            pending = (async () => {
+                const credentials = new SqliteCredentials(this.db, userId, this.key);
+                const models = createModels({ credentials, modelsStore: credentials.catalogStore(), authContext: {
+                        env: async () => undefined, fileExists: async () => false,
+                    } });
+                for (let provider of (this.options.providers ?? defaultProviders)()) {
+                    // A web user must never select a server AWS profile/credential chain
+                    // or a local Google service-account file. These built-ins still work
+                    // with user-supplied bearer/API keys, using their native wire APIs.
+                    if (provider.id === "amazon-bedrock" || provider.id === "google-vertex") {
+                        provider = { ...provider, auth: { ...provider.auth, apiKey: envApiKeyAuth(provider.id === "amazon-bedrock" ? "Bedrock bearer token" : "Google Cloud API key", []) } };
+                    }
+                    models.setProvider(provider);
+                }
+                await models.refresh({ allowNetwork: false });
+                return { models, credentials };
+            })();
+            this.users.set(userId, pending);
+            void pending.catch(() => { if (this.users.get(userId) === pending)
+                this.users.delete(userId); });
+        }
+        return pending;
+    }
+    async models(userId) { return (await this.user(userId)).models; }
+    async available(models, credentials) {
+        const connected = await credentials.list();
+        const names = new Map(models.getProviders().map((provider) => [provider.id, provider.name]));
+        const result = [];
+        for (const { providerId } of connected) {
+            try {
+                for (const model of await models.getAvailable(providerId))
+                    result.push({
+                        provider: model.provider, modelId: model.id, name: model.name, providerName: names.get(model.provider) ?? model.provider,
+                        thinkingLevels: getSupportedThinkingLevels(model), contextWindow: model.contextWindow, reasoning: model.reasoning,
+                        inputCost: model.cost.input, outputCost: model.cost.output,
+                    });
+            }
+            catch { /* A broken connection remains visible, but cannot admit work. */ }
+        }
+        return result;
+    }
+    async choices(userId) {
+        const { models, credentials } = await this.user(userId);
+        return this.available(models, credentials);
+    }
+    async validate(userId, ref) {
+        const choices = await this.choices(userId);
+        if (!choices.length)
+            throw new AgentError("Connect a provider on the Providers page first.", 409);
+        if (!ref || !choices.some((model) => model.provider === ref.provider && model.modelId === ref.modelId)) {
+            throw new AgentError("Select an available provider and model.", 409);
+        }
+        return { provider: ref.provider, modelId: ref.modelId };
+    }
+    async configured(userId, ref) {
+        const { models, credentials } = await this.user(userId);
+        if (!(await credentials.list()).some((entry) => entry.providerId === ref.provider))
+            return false;
+        try {
+            return (await models.getAvailable(ref.provider)).some((model) => model.id === ref.modelId);
+        }
+        catch {
+            return false;
+        }
+    }
+    async settings(userId) {
+        const { models, credentials } = await this.user(userId);
+        const connected = await credentials.list();
+        const summaries = await Promise.all(models.getProviders().map(async (provider) => {
+            const credential = connected.find((entry) => entry.providerId === provider.id);
+            let configured = false;
+            if (credential) {
+                try {
+                    configured = Boolean(await models.checkAuth(provider.id));
+                }
+                catch { /* sanitized status */ }
+            }
+            return {
+                id: provider.id, name: provider.name, connected: Boolean(credential), configured, authType: credential?.type,
+                methods: [
+                    ...(provider.auth.apiKey?.login ? [{ type: "api_key", label: provider.auth.apiKey.name }] : []),
+                    ...(provider.auth.oauth ? [{ type: "oauth", label: provider.auth.oauth.loginLabel ?? provider.auth.oauth.name }] : []),
+                ],
+            };
+        }));
+        const active = [...this.attempts.values()].find((attempt) => attempt.userId === userId && attempt.view.state === "pending");
+        return { storageReady: Boolean(this.key), providers: summaries, models: await this.available(models, credentials), activeLogin: active ? this.view(active) : undefined };
+    }
+    async refresh(userId) {
+        const { models, credentials } = await this.user(userId);
+        const result = await models.refresh({ providers: (await credentials.list()).map((entry) => entry.providerId), force: true, signal: AbortSignal.any([this.shutdown.signal, AbortSignal.timeout(20_000)]) });
+        await this.onChanged(userId);
+        if (result.aborted || result.errors.size)
+            throw new AgentError("Some model catalogs could not be refreshed. Previous models were kept.");
+    }
+    async disconnect(userId, providerId) {
+        const { models } = await this.user(userId);
+        for (const attempt of this.attempts.values()) {
+            if (attempt.userId === userId && attempt.view.providerId === providerId && attempt.view.state === "pending")
+                this.cancelAttempt(attempt);
+        }
+        await Promise.all([...this.attempts.values()].filter((attempt) => attempt.userId === userId && attempt.view.providerId === providerId).map((attempt) => attempt.done));
+        await models.logout(providerId);
+        await this.onChanged(userId);
+    }
+    async begin(userId, providerId, type) {
+        const { models, credentials } = await this.user(userId);
+        credentials.requireKey();
+        const provider = models.getProvider(providerId);
+        if (!provider || !(type === "oauth" ? provider.auth.oauth : provider.auth.apiKey?.login))
+            throw new AgentError("This provider does not support that login method.");
+        for (const [oldId, previous] of this.attempts) {
+            if (previous.userId === userId && previous.view.state !== "pending") {
+                await previous.done;
+                clearTimeout(previous.timer);
+                this.attempts.delete(oldId);
+            }
+        }
+        this.admit();
+        // Check after cleanup awaits; reservation below has no intervening await.
+        // Built-in OAuth flows may own fixed loopback callback ports, so serialize
+        // OAuth sign-ins across users as well as all sign-ins within one user.
+        for (const attempt of this.attempts.values()) {
+            if (attempt.view.state === "pending" && (attempt.userId === userId || (type === "oauth" && attempt.type === "oauth"))) {
+                throw new AgentError("Another provider sign-in is in progress. Finish or cancel it first.", 409);
+            }
+        }
+        const id = randomUUID();
+        const controller = new AbortController();
+        const attempt = {
+            userId, type, controller, listeners: new Set(), view: { id, providerId, state: "pending", events: [] }, done: Promise.resolve(),
+            timer: setTimeout(() => { this.cancelAttempt(attempt); this.attempts.delete(id); }, 10 * 60_000),
+        };
+        attempt.timer.unref();
+        this.attempts.set(id, attempt);
+        attempt.done = models.login(providerId, type, {
+            signal: controller.signal,
+            notify: (event) => {
+                if (attempt.view.state !== "pending")
+                    return;
+                attempt.view.events = [...attempt.view.events.slice(-19), event];
+                this.publish(attempt);
+            },
+            prompt: (input) => new Promise((resolve, reject) => {
+                const signal = AbortSignal.any([controller.signal, ...(input.signal ? [input.signal] : [])]);
+                const promptId = randomUUID();
+                const browserInput = { ...input };
+                delete browserInput.signal;
+                const cleanup = () => {
+                    signal.removeEventListener("abort", abort);
+                    if (attempt.view.prompt?.id === promptId) {
+                        delete attempt.view.prompt;
+                        delete attempt.answer;
+                        this.publish(attempt);
+                    }
+                };
+                const abort = () => { cleanup(); reject(new Error("Login prompt cancelled")); };
+                attempt.view.prompt = { id: promptId, input: browserInput };
+                attempt.answer = (value) => { cleanup(); resolve(value); };
+                this.publish(attempt);
+                signal.addEventListener("abort", abort, { once: true });
+                if (signal.aborted)
+                    abort();
+            }),
+        }, { getDeviceId: () => this.deviceId, agentName: "HyperVibes" }).then(async () => {
+            if (controller.signal.aborted)
+                return;
+            await models.refresh({ providers: [providerId], signal: AbortSignal.any([controller.signal, AbortSignal.timeout(20_000)]) });
+            attempt.view.state = "complete";
+            delete attempt.view.prompt;
+            this.publish(attempt);
+            await this.onChanged(userId);
+        }).catch(() => {
+            if (attempt.view.state === "pending") {
+                attempt.view.state = "failed";
+                attempt.view.error = "Provider sign-in failed. Check your credentials and try again. For OAuth, check that its callback port is available.";
+            }
+            delete attempt.view.prompt;
+            delete attempt.answer;
+            this.publish(attempt);
+        });
+        return this.view(attempt);
+    }
+    owned(userId, id) {
+        this.admit();
+        const attempt = this.attempts.get(id);
+        if (!attempt || attempt.userId !== userId)
+            throw new AgentError("Provider sign-in not found or expired.", 404);
+        return attempt;
+    }
+    view(attempt) { return structuredClone(attempt.view); }
+    status(userId, id) { return this.view(this.owned(userId, id)); }
+    publish(attempt) {
+        for (const listener of attempt.listeners)
+            listener(this.view(attempt));
+    }
+    watchLogin(userId, id, signal, publish) {
+        const attempt = this.owned(userId, id);
+        if (signal.aborted)
+            return Promise.resolve();
+        return new Promise((resolve) => {
+            const stop = () => {
+                attempt.listeners.delete(publish);
+                signal.removeEventListener("abort", stop);
+                resolve();
+            };
+            attempt.listeners.add(publish);
+            signal.addEventListener("abort", stop, { once: true });
+            publish(this.view(attempt));
+        });
+    }
+    answer(userId, id, promptId, value) {
+        const attempt = this.owned(userId, id);
+        if (attempt.view.state !== "pending" || attempt.view.prompt?.id !== promptId || !attempt.answer)
+            throw new AgentError("This sign-in prompt has expired.", 409);
+        const input = attempt.view.prompt.input;
+        // Text prompts can intentionally accept blank (e.g. Copilot's default
+        // github.com domain). Secret/code/select prompts always require a value.
+        if (value.length > 16_000 || (input.type !== "text" && !value.trim()))
+            throw new AgentError("Enter a valid sign-in response (maximum 16000 characters).");
+        if (input.type === "select" && !input.options.some((option) => option.id === value.trim()))
+            throw new AgentError("Select one of the sign-in options.");
+        // Copilot's native enterprise prompt otherwise permits arbitrary backend
+        // network destinations. Custom endpoint configuration is not in this slice.
+        if (attempt.view.providerId === "github-copilot" && input.type === "text" && value.trim() && value.trim() !== "github.com") {
+            throw new AgentError("Leave the domain blank for github.com. Custom enterprise endpoints are not supported yet.");
+        }
+        attempt.answer(value.trim());
+        return this.view(attempt);
+    }
+    cancelAttempt(attempt) {
+        if (attempt.view.state === "pending") {
+            attempt.view.state = "cancelled";
+            attempt.controller.abort();
+            delete attempt.view.prompt;
+            delete attempt.answer;
+            this.publish(attempt);
+        }
+    }
+    async cancel(userId, id) {
+        const attempt = this.owned(userId, id);
+        this.cancelAttempt(attempt);
+        await attempt.done;
+    }
+    async close() {
+        this.stopping = true;
+        this.shutdown.abort();
+        for (const attempt of this.attempts.values()) {
+            clearTimeout(attempt.timer);
+            this.cancelAttempt(attempt);
+        }
+        await Promise.all([...this.attempts.values()].map((attempt) => attempt.done));
+        for (const user of this.users.values())
+            await (await user).credentials.drain();
+        this.attempts.clear();
+        this.users.clear();
+    }
+}

package/dist/research/artifacts.js

@@ -0,0 +1,151 @@
+import { createHash, randomUUID } from "node:crypto";
+import { AgentError } from "../agents/agent-input.js";
+export const artifactTypes = ["text/markdown", "text/plain", "text/csv", "application/json", "image/png", "image/jpeg", "image/webp"];
+const columns = `id,agent_id AS agentId,title,description,media_type AS mediaType,size,tags,instrument,interval,created_at AS createdAt,expires_at AS expiresAt,conversation_id AS conversationId,task_id AS taskId,EXISTS(SELECT 1 FROM hv_memory_artifacts m WHERE m.agent_id=a.agent_id AND (m.artifact_id=a.id OR m.artifact_id IN(SELECT parent FROM hv_artifact_links WHERE child=a.id))) AS protectedByMemory`;
+// Only a one-level report -> attachment graph is allowed. An unexpired report
+// protects its children even when their own temporary retention has elapsed.
+export const artifactVisibleSql = `(a.expires_at IS NULL OR a.expires_at>? OR EXISTS(SELECT 1 FROM hv_memory_artifacts m WHERE m.agent_id=a.agent_id AND m.artifact_id=a.id) OR EXISTS(SELECT 1 FROM hv_artifact_links l JOIN hv_artifacts p ON p.id=l.parent WHERE l.child=a.id AND (p.expires_at IS NULL OR p.expires_at>? OR EXISTS(SELECT 1 FROM hv_memory_artifacts m WHERE m.agent_id=p.agent_id AND m.artifact_id=p.id))))`;
+const visible = artifactVisibleSql;
+const memoryProtected = `SELECT 1 FROM hv_memory_artifacts m WHERE m.agent_id=? AND (m.artifact_id=? OR m.artifact_id IN (SELECT parent FROM hv_artifact_links WHERE child=?)) LIMIT 1`;
+const meta = (row) => ({ ...row, tags: JSON.parse(row.tags), protectedByMemory: Boolean(row.protectedByMemory) });
+const maxBytes = 5 * 1024 * 1024;
+function text(value, max, label) { if (typeof value !== "string" || value.length > max)
+    throw new AgentError(`Invalid ${label}`); return value.trim(); }
+/** Payloads are immutable, root-Agent scoped and never stored in Pi documents. */
+export class ArtifactService {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    async cleanupTx(tx, now) {
+        // Delete expired parents first; child references no longer protect them.
+        await tx.run(`DELETE FROM hv_artifacts WHERE id IN(SELECT a.id FROM hv_artifacts a WHERE NOT ${visible} LIMIT 100)`, now, now);
+    }
+    async cleanup(now = Date.now()) {
+        await this.db.transaction((tx) => this.cleanupTx(tx, now));
+        // No implicit rebuild of an existing NONE database. Fresh profiles can
+        // reclaim space in small batches; WAL checkpointing remains separate.
+        await this.db.all("PRAGMA incremental_vacuum(256)");
+    }
+    async create(agentId, operationKey, input, producer = {}) {
+        const title = text(input.title, 160, "title");
+        if (!title || !artifactTypes.includes(input.mediaType))
+            throw new AgentError("Invalid artifact type/title");
+        const description = text(input.description ?? "", 1000, "description");
+        if (typeof input.content !== "string" || input.content.length > maxBytes * 1.4)
+            throw new AgentError("Artifact exceeds 5 MiB");
+        const image = input.mediaType.startsWith("image/");
+        if (image !== (input.encoding === "base64"))
+            throw new AgentError("Images require base64; text requires UTF-8");
+        const payload = Buffer.from(input.content, image ? "base64" : "utf8");
+        // Round-trip validation avoids permissive decoding and deep-regex stack
+        // exhaustion on multi-megabyte images.
+        if (image && payload.toString("base64") !== input.content)
+            throw new AgentError("Invalid base64");
+        if (!payload.length || payload.length > maxBytes)
+            throw new AgentError("Artifacts must contain 1 byte to 5 MiB");
+        if (image) {
+            const valid = input.mediaType === "image/png" ? payload.subarray(0, 8).equals(Buffer.from([137, 80, 78, 71, 13, 10, 26, 10])) : input.mediaType === "image/jpeg" ? payload[0] === 255 && payload[1] === 216 && payload[2] === 255 : payload.toString("ascii", 0, 4) === "RIFF" && payload.toString("ascii", 8, 12) === "WEBP";
+            if (!valid)
+                throw new AgentError("Image signature does not match its type");
+        }
+        if (input.mediaType === "application/json") {
+            try {
+                JSON.parse(input.content);
+            }
+            catch {
+                throw new AgentError("Invalid JSON artifact");
+            }
+        }
+        if (input.tags && (!Array.isArray(input.tags) || input.tags.length > 12))
+            throw new AgentError("At most 12 tags");
+        const tags = [...new Set((input.tags ?? []).map((tag) => text(tag, 40, "tag").toLowerCase()))].filter(Boolean).sort();
+        const instrument = text(input.instrument ?? "", 64, "instrument"), interval = text(input.interval ?? "", 8, "interval");
+        const embedded = input.mediaType === "text/markdown" ? [...input.content.matchAll(/artifact:([a-f0-9-]{36})/g)].map((match) => match[1]) : [];
+        const attachments = [...new Set([...(input.attachments ?? []), ...embedded])].sort();
+        if (attachments.length > 20 || attachments.some((id) => !/^[a-f0-9-]{36}$/.test(id)))
+            throw new AgentError("Invalid attachments (maximum 20)");
+        if (attachments.length && input.mediaType !== "text/markdown")
+            throw new AgentError("Only Markdown reports may contain attachments");
+        const hash = createHash("sha256").update(JSON.stringify({ title, description, mediaType: input.mediaType, tags, instrument, interval, attachments, retained: Boolean(input.retained) })).update(payload).digest("hex");
+        return this.db.transaction(async (tx) => {
+            const existing = await tx.get("SELECT artifact_id AS id,request_hash FROM hv_artifact_receipts WHERE agent_id=? AND operation_key=?", agentId, operationKey);
+            if (existing) {
+                if (existing.request_hash !== hash)
+                    throw new AgentError("Artifact operation key reused with different content", 409);
+                return this.metadata(tx, agentId, existing.id);
+            }
+            await this.cleanupTx(tx, Date.now());
+            for (const id of attachments) {
+                const child = await this.metadata(tx, agentId, id);
+                if (child.mediaType === "text/markdown")
+                    throw new AgentError("Nested reports are not supported");
+            }
+            const usage = await tx.get("SELECT coalesce(sum(size),0) AS bytes,count(*) AS total FROM hv_artifacts WHERE agent_id=?", agentId);
+            if ((usage?.bytes ?? 0) + payload.length > 100 * 1024 * 1024 || (usage?.total ?? 0) >= 2000)
+                throw new AgentError("Agent artifact quota reached. Delete old artifacts.", 409);
+            const id = randomUUID(), now = Date.now();
+            await tx.run(`INSERT INTO hv_artifacts(id,agent_id,title,description,media_type,payload,size,tags,instrument,interval,conversation_id,task_id,created_at,expires_at) VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?,?)`, id, agentId, title, description, input.mediaType, payload, payload.length, JSON.stringify(tags), instrument, interval, producer.conversationId ?? null, producer.taskId ?? null, now, input.retained ? null : now + 7 * 86400_000);
+            await tx.run("INSERT INTO hv_artifact_receipts(agent_id,operation_key,request_hash,artifact_id) VALUES (?,?,?,?)", agentId, operationKey, hash, id);
+            for (const child of attachments)
+                await tx.run("INSERT INTO hv_artifact_links(parent,child) VALUES (?,?)", id, child);
+            return this.metadata(tx, agentId, id);
+        });
+    }
+    /** Trusted tool task identity is immutable; reuse its original exported snapshot. */
+    async operation(agentId, operationKey) {
+        return this.db.transaction(async (tx) => {
+            const receipt = await tx.get("SELECT artifact_id AS id FROM hv_artifact_receipts WHERE agent_id=? AND operation_key=?", agentId, operationKey);
+            return receipt ? this.metadata(tx, agentId, receipt.id) : undefined;
+        });
+    }
+    async metadata(tx, agentId, id) {
+        const now = Date.now();
+        const row = await tx.get(`SELECT ${columns} FROM hv_artifacts a WHERE a.agent_id=? AND a.id=? AND ${visible}`, agentId, id, now, now);
+        if (!row)
+            throw new AgentError("Artifact unavailable or expired", 404);
+        return meta(row);
+    }
+    async list(agentId, filters = {}) {
+        const offset = filters.offset ?? 0;
+        if (!Number.isSafeInteger(offset) || offset < 0 || offset > 10000)
+            throw new AgentError("Invalid artifact offset");
+        const now = Date.now();
+        const rows = await this.db.all(`SELECT ${columns} FROM hv_artifacts a WHERE agent_id=? AND ${visible} AND (?='' OR instrument=?) AND (?='' OR interval=?) AND (?='' OR EXISTS(SELECT 1 FROM json_each(a.tags) WHERE value=?)) AND (?='' OR instr(lower(title||' '||description),lower(?))>0) ORDER BY created_at DESC,id DESC LIMIT 51 OFFSET ?`, agentId, now, now, filters.instrument ?? "", filters.instrument ?? "", filters.interval ?? "", filters.interval ?? "", filters.tag ?? "", filters.tag ?? "", filters.query ?? "", filters.query ?? "", offset);
+        return { items: rows.slice(0, 50).map(meta), nextOffset: rows.length > 50 ? offset + 50 : null };
+    }
+    async get(agentId, id) {
+        return this.db.transaction(async (tx) => {
+            const item = await this.metadata(tx, agentId, id);
+            const row = (await tx.get("SELECT payload FROM hv_artifacts WHERE id=? AND agent_id=?", id, agentId));
+            const attachments = await tx.all("SELECT a.id,a.title,a.media_type AS mediaType FROM hv_artifact_links l JOIN hv_artifacts a ON a.id=l.child WHERE l.parent=? AND a.agent_id=?", id, agentId);
+            return { ...item, payload: Buffer.from(row.payload), attachments };
+        });
+    }
+    async read(agentId, id, offset = 0, limit = 16000) {
+        if (!Number.isSafeInteger(offset) || offset < 0 || !Number.isSafeInteger(limit) || limit < 1 || limit > 16000)
+            throw new AgentError("Invalid read bounds");
+        const { payload, attachments, ...item } = await this.get(agentId, id);
+        const content = item.mediaType.startsWith("image/") ? null : payload.toString("utf8");
+        return { ...item, attachments, content: content?.slice(offset, offset + limit) ?? null, nextOffset: content && offset + limit < content.length ? offset + limit : null };
+    }
+    async retention(agentId, id, retained) {
+        await this.db.transaction(async (tx) => {
+            await this.metadata(tx, agentId, id);
+            if (!retained && await tx.get(memoryProtected, agentId, id, id))
+                throw new AgentError("Artifact is evidence referenced by a memory; retention cannot be removed.", 409);
+            await tx.run("UPDATE hv_artifacts SET expires_at=? WHERE agent_id=? AND id=?", retained ? null : Date.now() + 7 * 86400_000, agentId, id);
+        });
+    }
+    async remove(agentId, id) {
+        await this.db.transaction(async (tx) => {
+            await this.metadata(tx, agentId, id);
+            if (await tx.get(memoryProtected, agentId, id, id))
+                throw new AgentError("Artifact is evidence referenced by a memory and cannot be deleted.", 409);
+            const ref = await tx.get("SELECT l.parent FROM hv_artifact_links l JOIN hv_artifacts p ON p.id=l.parent WHERE l.child=? AND (p.expires_at IS NULL OR p.expires_at>? OR EXISTS(SELECT 1 FROM hv_memory_artifacts m WHERE m.agent_id=p.agent_id AND m.artifact_id=p.id)) LIMIT 1", id, Date.now());
+            if (ref)
+                throw new AgentError("Artifact is attached to a report. Delete the report first.", 409);
+            await tx.run("DELETE FROM hv_artifacts WHERE agent_id=? AND id=?", agentId, id);
+        });
+    }
+}

package/dist/research/call-queue.js

@@ -0,0 +1,43 @@
+/** Per-script FIFO admission. Closing rejects waiters; active operations own their cancellation. */
+export class CallQueue {
+    concurrency;
+    active = 0;
+    waiting = [];
+    failure;
+    constructor(concurrency) {
+        this.concurrency = concurrency;
+        if (!Number.isSafeInteger(concurrency) || concurrency < 1)
+            throw new Error("Invalid call concurrency");
+    }
+    get closed() { return this.failure !== undefined; }
+    get saturated() { return this.active >= this.concurrency; }
+    run(operation) {
+        if (this.failure)
+            return Promise.reject(this.failure.reason);
+        return new Promise((resolve, reject) => {
+            const start = () => {
+                this.active++;
+                void Promise.resolve().then(() => {
+                    if (this.failure)
+                        throw this.failure.reason;
+                    return operation();
+                }).then(resolve, reject).finally(() => {
+                    this.active--;
+                    if (!this.failure)
+                        this.waiting.shift()?.start();
+                });
+            };
+            if (this.active < this.concurrency)
+                start();
+            else
+                this.waiting.push({ start, reject });
+        });
+    }
+    close(reason) {
+        if (this.failure)
+            return;
+        this.failure = { reason };
+        for (const waiter of this.waiting.splice(0))
+            waiter.reject(reason);
+    }
+}

package/dist/research/contracts.js

@@ -0,0 +1,37 @@
+import { Type } from "@earendil-works/pi-ai";
+const nonnegativeInteger = Type.Integer({ minimum: 0 });
+const nullableInteger = Type.Union([nonnegativeInteger, Type.Null()]);
+const epochSeconds = Type.Integer({ minimum: 0, description: "Unix epoch seconds (UTC)" });
+const nullableEpochSeconds = Type.Union([epochSeconds, Type.Null()]);
+const epochMilliseconds = Type.Integer({ minimum: 0, description: "Unix epoch milliseconds (UTC)" });
+const nullableEpochMilliseconds = Type.Union([epochMilliseconds, Type.Null()]);
+const nullableMoney = Type.Union([Type.String(), Type.Null()]);
+const metadataFields = {
+    id: Type.String(), agentId: Type.String(), title: Type.String(), description: Type.String(), mediaType: Type.String(), size: Type.Integer({ minimum: 1 }),
+    tags: Type.Array(Type.String(), { maxItems: 12 }), instrument: Type.String(), interval: Type.String(), createdAt: epochMilliseconds, expiresAt: nullableEpochMilliseconds,
+    conversationId: nullableInteger, taskId: nullableInteger, protectedByMemory: Type.Optional(Type.Boolean()),
+};
+export const ArtifactMetaSchema = Type.Object(metadataFields);
+export const ArtifactReadSchema = Type.Object({ ...metadataFields,
+    attachments: Type.Array(Type.Object({ id: Type.String(), title: Type.String(), mediaType: Type.String() })),
+    content: Type.Union([Type.String(), Type.Null()]), nextOffset: nullableInteger,
+});
+export const ArtifactListSchema = Type.Object({ items: Type.Array(ArtifactMetaSchema, { maxItems: 50 }), nextOffset: nullableInteger });
+export const ExportSchema = Type.Object({ artifact: ArtifactMetaSchema, reference: Type.String(), summary: Type.Record(Type.String(), Type.Unknown()) });
+export const CandleCoverageSchema = Type.Object({ complete: Type.Boolean(), returned: nonnegativeInteger, expected: Type.Number({ minimum: 0 }), sourceLimit: Type.String(), closedOnly: Type.Literal(true) });
+export const DatasetSchema = Type.Object({ count: nonnegativeInteger, firstTime: nullableEpochSeconds, lastTime: nullableEpochSeconds });
+const candle = Type.Object({ time: Type.Number({ description: "Candle open time in Unix epoch seconds (UTC)" }), open: Type.Number(), high: Type.Number(), low: Type.Number(), close: Type.Number(), volume: Type.Number() });
+export const CandleResultSchema = Type.Union([Type.Object({ coin: Type.String(), interval: Type.String(), start: epochMilliseconds, end: epochMilliseconds, pageEnd: epochMilliseconds, dataset: DatasetSchema, candles: Type.Array(candle, { maxItems: 2000 }), nextStart: nullableEpochMilliseconds, coverage: CandleCoverageSchema }), ExportSchema]);
+const trade = Type.Object({
+    id: Type.String(), symbol: Type.String(), direction: Type.String(), status: Type.String(), openedAt: epochMilliseconds, lastActivityAt: epochMilliseconds, closedAt: nullableEpochMilliseconds,
+    remainingSize: Type.String(), entrySize: Type.String(), exitSize: Type.String(), entryNotional: Type.String(), exitNotional: Type.String(),
+    grossPnl: Type.String(), fees: Type.String(), funding: nullableMoney, net: nullableMoney, feeCoverage: Type.Boolean(), coverageReason: Type.Union([Type.String(), Type.Null()]),
+});
+export const JournalResultSchema = Type.Union([Type.Object({
+        trades: Type.Optional(Type.Array(trade, { maxItems: 1000 })), next: Type.Union([Type.Object({ time: epochMilliseconds, id: Type.String() }), Type.Null()]),
+        performance: Type.Object({ scope: Type.String(), closed: nonnegativeInteger, knownNetCount: nonnegativeInteger, knownNetSum: Type.String(), knownNetWins: nonnegativeInteger, grossPnl: Type.String(), fees: Type.String() }),
+        coverage: Type.Object({ complete: Type.Boolean(), historyLimited: Type.Boolean(), filter: Type.String(), truncated: Type.Boolean(),
+            catchUp: Type.Optional(Type.Object({ attempted: Type.Boolean(), limitation: Type.Union([Type.String(), Type.Null()]) })),
+            sync: Type.Array(Type.Object({ stream: Type.String(), cursor: epochMilliseconds, updated_at: nullableEpochMilliseconds, error: Type.Union([Type.String(), Type.Null()]) })),
+        }),
+    }), ExportSchema]);

package/dist/research/evidence.js

@@ -0,0 +1,43 @@
+/** Actual candle-open bounds in UTC seconds, not requested millisecond boundaries. */
+export function describeDataset(rows) {
+    return { count: rows.length, firstTime: rows[0]?.time ?? null, lastTime: rows.at(-1)?.time ?? null };
+}
+export const utcFormattingExample = `function utcMilliseconds(value) {
+  if (typeof value !== 'number' || !Number.isFinite(value)) return null;
+  const date = new Date(value);
+  return Number.isFinite(date.getTime()) ? date.toISOString() : null;
+}
+function utcSeconds(value) { return typeof value === 'number' ? utcMilliseconds(value * 1000) : null; }
+function datasetEvidence(dataset) {
+  return dataset ? {...dataset, firstTimeUtc:utcSeconds(dataset.firstTime ?? dataset.firstOpenTime), lastTimeUtc:utcSeconds(dataset.lastTime ?? dataset.lastOpenTime)} : null;
+}`;
+export const technicalEvidenceExample = `${utcFormattingExample}
+const latest = candleResult.candles.at(-1);
+const priceValid = candleResult.coverage.complete && candleResult.nextStart === null && latest && Number.isFinite(latest.close);
+function scalar(result, indicator, period, output) {
+  const point = result.values?.at(-1), value = point?.value?.[output];
+  return priceValid && result.coin === candleResult.coin && result.interval === candleResult.interval &&
+    result.indicatorId === 'builtin:' + indicator && result.resolvedInputs.period === period &&
+    (!('source' in result.resolvedInputs) || result.resolvedInputs.source === 'close') &&
+    result.coverage.complete && point?.time === latest.time && typeof value === 'number' && Number.isFinite(value) ? value : null;
+}
+const ema20 = scalar(ema20Result, 'ema', 20, 'EMA'), ema50 = scalar(ema50Result, 'ema', 50, 'EMA');
+const atr = scalar(atrResult, 'atr', atrResult.resolvedInputs?.period, 'ATR');
+function provenance(result) {
+  return {coin:result.coin, interval:result.interval, requestedStartUtc:utcMilliseconds(result.start), effectiveEndExclusiveUtc:utcMilliseconds(result.end),
+    input:datasetEvidence(result.dataset), output:datasetEvidence(result.outputDataset), coverage:result.coverage,
+    inputs:result.resolvedInputs ?? null, version:result.version ?? null, sourceHash:result.sourceHash ?? null, resultHash:result.resultHash ?? null};
+}
+text({datasets:{candles:provenance(candleResult), ema20:provenance(ema20Result), ema50:provenance(ema50Result), atr:provenance(atrResult)},
+  latestClosed:latest ? {...latest, openTimeUtc:utcSeconds(latest.time)} : null,
+  facts:{priceBelowEma20:ema20 === null ? null : latest.close < ema20,
+    ema20AboveEma50:ema20 === null || ema50 === null ? null : ema20 > ema50,
+    atrPercent:atr === null || latest.close <= 0 ? null : atr / latest.close * 100}});`;
+export const bollingerEvidenceExample = `const bandPoint = bollingerResult.values?.at(-1), bands = bandPoint?.value;
+const bandsValid = priceValid && bollingerResult.coin === candleResult.coin && bollingerResult.interval === candleResult.interval &&
+  bollingerResult.indicatorId === 'builtin:bollinger' && bollingerResult.resolvedInputs.source === 'close' &&
+  bollingerResult.coverage.complete && bandPoint?.time === latest.time && bands &&
+  ['Lower','Middle','Upper'].every(key => typeof bands[key] === 'number' && Number.isFinite(bands[key])) && bands.Lower <= bands.Middle && bands.Middle <= bands.Upper;
+text({bollinger:{openTimeUtc:utcSeconds(bandPoint?.time), value:bandsValid ? bands : null, provenance:provenance(bollingerResult)},
+  facts:{priceAboveUpperBand:bandsValid ? latest.close > bands.Upper : null, priceBelowLowerBand:bandsValid ? latest.close < bands.Lower : null}});`;
+export const technicalEvidenceInstructions = `Calculate comparison flags in Code Mode before writing prose; Check the final prose against the flags. Facts are not forecasts. Quote the emitted ISO UTC strings verbatim. Request start/end are milliseconds, candle-open times are seconds. All indicators use point.value.<outputId>: EMA, ATR, RSI, ADX, MACD/Signal/Histogram and Lower/Middle/Upper. Null/missing/nonfinite/misaligned/non-close-source evidence is unknown, never zero or fabricated false. Report actual seed/output bounds, coverage, resolvedInputs, concrete version/sourceHash/resultHash and per-output finite availability. A finite value does not prove initialization effects have disappeared. About 5× the longest period plus trailing history is a seed recommendation, not universal stability. A one-value request still computes the entire seed window. No universal stable/requiredInputs claim exists for arbitrary PineScript. Use indicator_get for exact keys. Example (bind these results using selected tools on a common closed window):\n\n${technicalEvidenceExample}\n\n${bollingerEvidenceExample}`;

package/dist/research/journal.js

@@ -0,0 +1,30 @@
+import { amount } from "../hyperliquid/journal-decimal.js";
+import { AgentError } from "../agents/agent-input.js";
+/** Reads only application journal tables; no private harness storage. */
+export async function researchJournal(db, agentId, start, end, limit, before) {
+    if (![start, end, limit].every(Number.isSafeInteger) || start < 0 || end <= start || limit < 1 || limit > 1000 || (before && (!Number.isSafeInteger(before.time) || before.id.length > 128)))
+        throw new AgentError("Invalid journal bounds");
+    return db.transaction(async (tx) => {
+        const agent = await tx.get("SELECT trading_account_address AS account FROM hv_agents WHERE id=?", agentId);
+        if (!agent?.account)
+            throw new AgentError("Agent has no trading account");
+        const account = agent.account.toLowerCase();
+        const rows = await tx.all(`SELECT id,time,json_remove(data,'$.parts') AS data FROM hv_journal_entries WHERE account=? AND kind='trade' AND active=1 AND time>=? AND time<? AND (time<? OR (time=? AND id<?)) ORDER BY time DESC,id DESC LIMIT ?`, account, start, end, before?.time ?? end, before?.time ?? end, before?.id ?? "", limit + 1);
+        const sync = await tx.all("SELECT stream,cursor,updated_at,error FROM hv_journal_sync WHERE account=?", account);
+        const state = await tx.get("SELECT revision,projected_revision,history_limited FROM hv_journal_accounts WHERE account=?", account);
+        const complete = Boolean(state && !state.history_limited && state.revision === state.projected_revision && sync.length === 3 && sync.every((row) => row.updated_at && !row.error && row.cursor >= end));
+        const trades = rows.slice(0, limit).map((row) => {
+            const trade = JSON.parse(row.data);
+            return { ...trade, funding: complete ? trade.funding : null, net: complete ? trade.net : null };
+        });
+        const closed = trades.filter((trade) => trade.status === "closed");
+        const knownNet = closed.filter((trade) => trade.net !== null);
+        const sum = (values) => values.reduce((total, value) => total.add(amount(value)), amount("0")).toString();
+        const tail = rows[Math.min(limit, rows.length) - 1];
+        return { trades, next: rows.length > limit && tail ? { time: tail.time, id: tail.id } : null,
+            performance: { scope: "returned closed trades only; not account equity/returns", closed: closed.length, knownNetCount: knownNet.length,
+                knownNetSum: sum(knownNet.map((trade) => trade.net)), knownNetWins: knownNet.filter((trade) => amount(trade.net).sign > 0).length,
+                grossPnl: sum(closed.map((trade) => trade.grossPnl)), fees: sum(closed.map((trade) => trade.fees)) },
+            coverage: { complete, historyLimited: state?.history_limited === 1, sync, filter: "lastActivityAt in [start,end); persistent trade projections may change during sync", truncated: rows.length > limit } };
+    });
+}