hypervibes 0.0.0-stage → 0.4.0

package/dist/memory/insight-service.js

@@ -0,0 +1,117 @@
+import { randomUUID } from "node:crypto";
+import { AgentError } from "../agents/agent-input.js";
+import { insightMutation, insightScope } from "./insight-contracts.js";
+import { memoryRef, parseMemoryRef, timestamp } from "./memory-contracts.js";
+import { assertActiveActor, operationReplay, requestHash, saveOperation } from "./operations.js";
+import { fields, integer } from "./validation.js";
+export class InsightConflict extends AgentError {
+    currentVersion;
+    constructor(currentVersion) {
+        super(`Insights changed to v${currentVersion}; reread and reconcile your draft`, 409);
+        this.currentVersion = currentVersion;
+    }
+}
+export class InsightService {
+    db;
+    authorize;
+    clock;
+    constructor(db, authorize, clock = Date.now) {
+        this.db = db;
+        this.authorize = authorize;
+        this.clock = clock;
+    }
+    async checkScope(tx, agentId, scope) {
+        const owner = await tx.get("SELECT id FROM hv_agents WHERE id=?", agentId);
+        if (!owner)
+            throw new AgentError("Agent not found", 404);
+        if (scope.kind === "worker" && !await tx.get("SELECT id FROM hv_subagents WHERE agent_id=? AND id=? AND kind='worker'", agentId, scope.subagentId))
+            throw new AgentError("Worker not found in this Agent", 404);
+    }
+    set(tx, agentId, scope) {
+        return tx.get("SELECT id,current_version FROM hv_insight_sets WHERE agent_id=? AND scope_kind=? AND subagent_id IS ?", agentId, scope.kind, scope.kind === "worker" ? scope.subagentId : null);
+    }
+    /** Can be used inside the owning admission transaction, without re-entering the queue. */
+    async snapshotTx(tx, agentId, scope) {
+        await this.checkScope(tx, agentId, scope);
+        const set = await this.set(tx, agentId, scope);
+        if (!set || set.current_version === 0)
+            return { scope, version: 0, content: "" };
+        const row = await tx.get("SELECT content FROM hv_insight_revisions WHERE agent_id=? AND set_id=? AND version=?", agentId, set.id, set.current_version);
+        if (!row)
+            throw new Error("Insight head has no revision");
+        return { scope, version: set.current_version, content: row.content };
+    }
+    current(agentId, value) {
+        const scope = insightScope(value);
+        return this.db.transaction((tx) => this.snapshotTx(tx, agentId, scope));
+    }
+    append(actor, key, input) { return this.mutate(actor, key, "append", input); }
+    replace(actor, key, input) { return this.mutate(actor, key, "replace", input); }
+    async mutate(actor, key, operation, value) {
+        const input = insightMutation(value, operation), kind = operation === "append" ? "append_insight" : "replace_insights";
+        const hash = requestHash(actor, kind, input);
+        return this.db.transaction(async (tx) => {
+            const replay = await operationReplay(tx, actor, key, kind, hash);
+            if (replay)
+                return replay;
+            const now = timestamp(this.clock());
+            await assertActiveActor(tx, actor);
+            await this.authorize(tx, actor, kind, input.scope.kind === "worker" ? input.scope.subagentId : null);
+            await this.checkScope(tx, actor.agentId, input.scope);
+            let set = await this.set(tx, actor.agentId, input.scope);
+            if (!set) {
+                set = { id: randomUUID(), current_version: 0 };
+                await tx.run("INSERT INTO hv_insight_sets(id,agent_id,scope_kind,subagent_id,current_version,updated_at) VALUES (?,?,?,?,0,?)", set.id, actor.agentId, input.scope.kind, input.scope.kind === "worker" ? input.scope.subagentId : null, now);
+            }
+            if (operation === "replace" && set.current_version !== input.expectedVersion)
+                throw new InsightConflict(set.current_version);
+            let content = input.content;
+            const refs = new Set(input.evidenceRefs.map(parseMemoryRef));
+            if (operation === "append" && set.current_version > 0) {
+                const previous = await tx.get("SELECT content FROM hv_insight_revisions WHERE agent_id=? AND set_id=? AND version=?", actor.agentId, set.id, set.current_version);
+                if (!previous)
+                    throw new Error("Insight head has no revision");
+                content = previous.content ? `${previous.content}\n\n---\n\n${content}` : content;
+                const inherited = await tx.all("SELECT memory_number FROM hv_insight_revision_memories WHERE agent_id=? AND set_id=? AND version=?", actor.agentId, set.id, set.current_version);
+                for (const ref of inherited)
+                    refs.add(ref.memory_number);
+            }
+            if (content.length > 8000)
+                throw new AgentError("Insight document exceeds 8,000 characters; reread and consolidate using replace", 409);
+            for (const ref of refs)
+                if (!await tx.get("SELECT number FROM hv_memories WHERE agent_id=? AND number=?", actor.agentId, ref))
+                    throw new AgentError("Evidence memory not found in this Agent", 404);
+            const version = integer(set.current_version + 1, 1, Number.MAX_SAFE_INTEGER - 1, "insight version");
+            await tx.run("INSERT INTO hv_insight_revisions(agent_id,set_id,version,content,operation,reason,created_at,actor_user_id,producer_subagent_id,source_run_id,conversation_id,tool_task_id) VALUES (?,?,?,?,?,?,?,?,?,?,?,?)", actor.agentId, set.id, version, content, operation, input.reason, now, actor.userId, actor.subagentId, actor.runId, actor.conversationId, actor.toolTaskId);
+            for (const ref of refs)
+                await tx.run("INSERT INTO hv_insight_revision_memories(agent_id,set_id,version,memory_number) VALUES (?,?,?,?)", actor.agentId, set.id, version, ref);
+            await tx.run("UPDATE hv_insight_sets SET current_version=?,updated_at=? WHERE agent_id=? AND id=?", version, now, actor.agentId, set.id);
+            return saveOperation(tx, actor, key, kind, hash, { scope: input.scope, version }, now);
+        });
+    }
+    async revision(agentId, value, version) {
+        const scope = insightScope(value);
+        integer(version, 1, Number.MAX_SAFE_INTEGER - 1, "revision version");
+        return this.db.transaction(async (tx) => {
+            await this.checkScope(tx, agentId, scope);
+            const set = await this.set(tx, agentId, scope);
+            const row = set && await tx.get("SELECT * FROM hv_insight_revisions WHERE agent_id=? AND set_id=? AND version=?", agentId, set.id, version);
+            if (!set || !row)
+                throw new AgentError("Insight revision not found", 404);
+            const refs = await tx.all("SELECT memory_number FROM hv_insight_revision_memories WHERE agent_id=? AND set_id=? AND version=? ORDER BY memory_number", agentId, set.id, version);
+            return { scope, version, content: row.content, operation: row.operation, reason: row.reason, createdAt: row.created_at, userId: row.actor_user_id, producerSubagentId: row.producer_subagent_id, sourceRunId: row.source_run_id, evidenceRefs: refs.map((ref) => memoryRef(ref.memory_number)) };
+        });
+    }
+    async history(agentId, value, options = {}) {
+        const scope = insightScope(value), input = fields(options, ["beforeVersion", "limit"]);
+        const before = input.beforeVersion === undefined ? Number.MAX_SAFE_INTEGER : integer(input.beforeVersion, 1, Number.MAX_SAFE_INTEGER, "history cursor");
+        const limit = input.limit === undefined ? 25 : integer(input.limit, 1, 25, "history page size");
+        return this.db.transaction(async (tx) => {
+            await this.checkScope(tx, agentId, scope);
+            const set = await this.set(tx, agentId, scope);
+            const rows = set ? await tx.all("SELECT version,operation,reason,created_at,actor_user_id,producer_subagent_id,source_run_id FROM hv_insight_revisions WHERE agent_id=? AND set_id=? AND version<? ORDER BY version DESC LIMIT ?", agentId, set.id, before, limit + 1) : [];
+            const items = rows.slice(0, limit).map((row) => ({ scope, version: row.version, operation: row.operation, reason: row.reason, createdAt: row.created_at, userId: row.actor_user_id, producerSubagentId: row.producer_subagent_id, sourceRunId: row.source_run_id }));
+            return { items, nextBeforeVersion: rows.length > limit ? items.at(-1).version : null };
+        });
+    }
+}

package/dist/memory/memory-contracts.js

@@ -0,0 +1,113 @@
+import { AgentError } from "../agents/agent-input.js";
+import { candleIntervals } from "../agents/candle-intervals.js";
+import { array, choice, fields, integer, object, text, unique } from "./validation.js";
+export const memoryToolNames = ["publish_research", "record_trade_decision", "publish_review", "list_memories", "get_memory", "get_trading_context", "get_insights", "append_insight", "replace_insights", "research_decisions", "research_execution_audit"];
+export const memoryKinds = ["research", "decision", "review"];
+export const relations = ["based_on", "corrects", "supersedes", "reviews"];
+export function memoryRef(number) {
+    integer(number, 1, Number.MAX_SAFE_INTEGER, "memory number");
+    return `m${number}`;
+}
+export function parseMemoryRef(value) {
+    if (typeof value !== "string" || !/^m[1-9][0-9]*$/.test(value) || value.trim() !== value)
+        throw new AgentError("Use an exact memory reference such as m42");
+    return integer(Number(value.slice(1)), 1, Number.MAX_SAFE_INTEGER, "memory reference");
+}
+export function reference(value) {
+    if (typeof value !== "string")
+        throw new AgentError("Use an exact memory reference such as m42");
+    parseMemoryRef(value);
+    return value;
+}
+// Unlike $, the final lookahead cannot match before a trailing newline.
+export const topicPattern = /^[a-z][a-z0-9_]{0,63}(?![\s\S])/;
+export function topic(value) {
+    if (typeof value !== "string" || !topicPattern.test(value) || value.trim() !== value)
+        throw new AgentError("Use a lowercase topic such as trend_setup");
+    return value;
+}
+/** Syntax only; the host must also check the current main-DEX instrument catalog. */
+export function instrument(value) {
+    if (typeof value !== "string" || !/^[A-Za-z0-9][A-Za-z0-9_-]{0,31}$/.test(value) || value.trim() !== value)
+        throw new AgentError("Use an exact main-DEX perpetual symbol");
+    return value;
+}
+export function interval(value) {
+    if (typeof value !== "string" || !Object.hasOwn(candleIntervals, value))
+        throw new AgentError("Unsupported analytical interval");
+    return value;
+}
+export const timestamp = (value) => integer(value, 0, Number.MAX_SAFE_INTEGER, "UTC epoch milliseconds");
+const strings = (value) => array(value, 20, (item) => text(item, 1000, "payload text"));
+const refs = (value) => unique(array(value, 20, reference)).sort();
+function researchData(value, depth = 0) {
+    if (depth > 32)
+        throw new AgentError("Research data exceeds 32 nesting levels");
+    if (value === null || typeof value === "string" || typeof value === "boolean")
+        return value;
+    if (typeof value === "number" && Number.isFinite(value))
+        return value;
+    if (Array.isArray(value))
+        return Array.from(value, (item) => researchData(item, depth + 1));
+    if (typeof value === "object" && value !== null)
+        return researchObject(value, depth);
+    throw new AgentError("Research data must contain only JSON values");
+}
+function researchObject(value, depth = 0) {
+    const row = object(value);
+    if ((Object.getPrototypeOf(row) !== Object.prototype && Object.getPrototypeOf(row) !== null) || Object.getOwnPropertySymbols(row).length !== 0)
+        throw new AgentError("Research data must be a plain JSON object");
+    return Object.fromEntries(Object.entries(row).map(([key, item]) => [key, researchData(item, depth + 1)]));
+}
+export function publicationInput(kind, value) {
+    const row = fields(value, ["topic", "instrument", "interval", "summary", "content", "artifactIds", "links", "payload", ...(kind === "research" ? ["evidenceAsOf", "requestedValidUntil"] : [])]);
+    const base = {
+        topic: topic(row.topic), instrument: row.instrument == null ? null : instrument(row.instrument), interval: row.interval == null ? null : interval(row.interval),
+        summary: text(row.summary, 500, "summary"), content: text(row.content, 16000, "content"),
+        artifactIds: unique(array(row.artifactIds ?? [], 20, (id) => {
+            if (typeof id !== "string" || !/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/.test(id) || id.trim() !== id)
+                throw new AgentError("Invalid artifact ID");
+            return id;
+        })).sort(),
+        links: array(row.links ?? [], 20, (item) => { const link = fields(item, ["ref", "relation"]); return { ref: reference(link.ref), relation: choice(link.relation, relations) }; }),
+    };
+    unique(base.links.map((link) => `${link.relation}:${link.ref}`));
+    base.links.sort((a, b) => parseMemoryRef(a.ref) - parseMemoryRef(b.ref) || a.relation.localeCompare(b.relation));
+    const p = row.payload;
+    let result;
+    if (kind === "research") {
+        const payload = researchObject(p === undefined ? {} : p);
+        if (!base.instrument || !base.interval)
+            throw new AgentError("Research requires an instrument and interval");
+        result = { ...base, kind, evidenceAsOf: timestamp(row.evidenceAsOf), requestedValidUntil: row.requestedValidUntil == null ? null : timestamp(row.requestedValidUntil), payload };
+    }
+    else if (kind === "decision") {
+        const payload = fields(p, ["version", "action", "direction", "reason", "researchRefs", "plan"]);
+        integer(payload.version, 1, 1, "payload version");
+        const action = choice(payload.action, ["enter", "hold", "skip", "reduce", "close", "protect"]);
+        const direction = payload.direction == null ? null : choice(payload.direction, ["long", "short"]);
+        if (action === "enter" && (!base.instrument || !direction || !payload.plan))
+            throw new AgentError("Entry decisions require instrument, direction, and protection plan");
+        result = { ...base, kind, payload: { version: 1, action, direction, reason: text(payload.reason, 4000, "reason"), researchRefs: refs(payload.researchRefs), plan: text(payload.plan, 4000, "plan", action !== "enter") } };
+    }
+    else {
+        const payload = fields(p, ["version", "start", "end", "coverage", "limitations", "findings", "recommendations", "memoryRefs"]);
+        integer(payload.version, 1, 1, "payload version");
+        const start = timestamp(payload.start), end = timestamp(payload.end);
+        if (end <= start || end - start > 90 * 86400_000)
+            throw new AgentError("Review window must be positive and at most 90 days");
+        result = { ...base, kind, payload: { version: 1, start, end, coverage: choice(payload.coverage, ["complete", "incomplete", "unknown"]), limitations: strings(payload.limitations), findings: strings(payload.findings), recommendations: strings(payload.recommendations), memoryRefs: refs(payload.memoryRefs) } };
+    }
+    if (new TextEncoder().encode(JSON.stringify(result.payload)).length > 16 * 1024)
+        throw new AgentError("Structured payload exceeds 16 KiB");
+    return result;
+}
+/** Model-supplied advisory requirements; callers never gain trading authority from them. */
+export function researchRequirements(value) {
+    const result = array(value, 20, (item) => {
+        const row = fields(item, ["subagentId", "topic", "interval", "maxAgeSeconds"]);
+        return { subagentId: text(row.subagentId, 100, "worker ID"), topic: topic(row.topic), interval: interval(row.interval), maxAgeSeconds: integer(row.maxAgeSeconds, 1, 7 * 86400, "research maximum age") };
+    });
+    unique(result.map((requirement) => `${requirement.subagentId}:${requirement.topic}:${requirement.interval}`));
+    return result;
+}

package/dist/memory/memory-service.js

@@ -0,0 +1,179 @@
+import { enqueueWorkerEvent } from "../agents/worker-events.js";
+import { AgentError } from "../agents/agent-input.js";
+import { candleIntervals } from "../agents/candle-intervals.js";
+import { artifactVisibleSql } from "../research/artifacts.js";
+import { assertActiveActor, operationReplay, requestHash, saveOperation } from "./operations.js";
+import { instrument, interval, memoryKinds, memoryRef, parseMemoryRef, publicationInput, researchRequirements, timestamp, topic } from "./memory-contracts.js";
+import { choice, fields, integer, text } from "./validation.js";
+/** Host validity cap: research cannot claim validity longer than this past its evidence. */
+export const maxResearchAgeSeconds = 7 * 86400;
+const columns = "number,kind,topic,instrument,interval,summary,created_at,evidence_as_of,valid_until,producer_subagent_id,source_run_id,retracted_at,retraction_reason";
+const intervalWidthSql = `CASE interval ${Object.entries(candleIntervals).map(([name, seconds]) => `WHEN '${name}' THEN ${seconds * 1000}`).join(" ")} END`;
+function statusSql(now) {
+    timestamp(now);
+    // Worker lifecycle controls future execution, not published evidence validity.
+    return `CASE WHEN kind!='research' THEN 'durable' WHEN retracted_at IS NOT NULL THEN 'retracted' WHEN evidence_as_of>${now} OR (${intervalWidthSql}) IS NULL OR evidence_as_of % (${intervalWidthSql}) != 0 THEN 'invalid_evidence' WHEN valid_until<=${now} THEN 'stale' ELSE 'fresh' END`;
+}
+function metadata(row, replacements) {
+    return { correctedBy: replacements?.correctedBy ?? null, supersededBy: replacements?.supersededBy ?? null, status: row.status, ref: memoryRef(row.number), kind: row.kind, topic: row.topic, instrument: row.instrument, interval: row.interval, summary: row.summary, createdAt: row.created_at, evidenceAsOf: row.evidence_as_of, validUntil: row.valid_until, producerSubagentId: row.producer_subagent_id, sourceRunId: row.source_run_id, retractedAt: row.retracted_at, retractionReason: row.retraction_reason };
+}
+export class MemoryService {
+    db;
+    authorize;
+    clock;
+    constructor(db, authorize, clock = Date.now) {
+        this.db = db;
+        this.authorize = authorize;
+        this.clock = clock;
+    }
+    publishResearch(actor, key, input) { return this.publish(actor, key, "research", input); }
+    recordDecision(actor, key, input) { return this.publish(actor, key, "decision", input); }
+    publishReview(actor, key, input) { return this.publish(actor, key, "review", input); }
+    async publish(actor, key, kind, value) {
+        const input = publicationInput(kind, value);
+        const operation = kind === "research" ? "publish_research" : kind === "decision" ? "record_trade_decision" : "publish_review";
+        const hash = requestHash(actor, operation, input);
+        return this.db.transaction(async (tx) => {
+            const replay = await operationReplay(tx, actor, key, operation, hash);
+            if (replay)
+                return replay;
+            const now = timestamp(this.clock());
+            await assertActiveActor(tx, actor);
+            await this.authorize(tx, actor, operation);
+            let deadline = null;
+            if (input.kind === "research") {
+                const width = candleIntervals[interval(input.interval)] * 1000;
+                if (input.evidenceAsOf > now || input.evidenceAsOf % width !== 0)
+                    throw new AgentError("Evidence must be an aligned closed-candle end boundary in UTC milliseconds, not in the future");
+                // Two bars is a fallback, not a strategy limit. Explicit analyst deadlines
+                // may be shorter or longer, but never exceed the evidence-based ceiling.
+                deadline = timestamp(Math.min(input.requestedValidUntil ?? input.evidenceAsOf + 2 * width, input.evidenceAsOf + maxResearchAgeSeconds * 1000));
+                if (deadline <= input.evidenceAsOf)
+                    throw new AgentError("Research validity must follow its evidence boundary");
+            }
+            const cited = input.kind === "decision" ? input.payload.researchRefs : input.kind === "review" ? input.payload.memoryRefs : [];
+            const links = [...input.links];
+            for (const ref of cited)
+                if (!links.some((link) => link.ref === ref && link.relation === (kind === "review" ? "reviews" : "based_on")))
+                    links.push({ ref, relation: kind === "review" ? "reviews" : "based_on" });
+            if (links.length > 20)
+                throw new AgentError("At most 20 combined memory relationships");
+            for (const link of links) {
+                const target = await this.row(tx, actor.agentId, parseMemoryRef(link.ref));
+                if (input.kind === "decision" && input.payload.researchRefs.includes(link.ref) && target.kind !== "research")
+                    throw new AgentError("Decision research refs must identify research publications");
+                if (link.relation === "corrects" || link.relation === "supersedes") {
+                    if (input.kind !== "research" || target.kind !== "research" || target.producer_subagent_id !== actor.subagentId || target.instrument !== input.instrument || target.topic !== input.topic || target.interval !== input.interval)
+                        throw new AgentError("Corrections and supersessions require the same research producer and stream");
+                    if (link.relation === "corrects") {
+                        if (input.evidenceAsOf !== target.evidence_as_of)
+                            throw new AgentError("A correction requires the same evidence boundary; use supersedes for newer evidence");
+                        deadline = Math.min(deadline, target.valid_until);
+                    }
+                    else if (input.evidenceAsOf <= target.evidence_as_of)
+                        throw new AgentError("Supersession requires strictly newer evidence; use corrects for the same evidence boundary");
+                }
+            }
+            for (const id of input.artifactIds) {
+                const evidence = await tx.get(`SELECT a.id FROM hv_artifacts a WHERE a.agent_id=? AND a.id=? AND ${artifactVisibleSql}`, actor.agentId, id, now, now);
+                if (!evidence)
+                    throw new AgentError("Artifact unavailable, foreign, or expired", 404);
+            }
+            // Linking retains existing bytes; never creates an alternative quota pool.
+            if (input.artifactIds.length) {
+                const usage = await tx.get("SELECT coalesce(sum(size),0) AS bytes,count(*) AS total FROM hv_artifacts WHERE agent_id=?", actor.agentId);
+                if ((usage?.bytes ?? 0) > 100 * 1024 * 1024 || (usage?.total ?? 0) > 2000)
+                    throw new AgentError("Artifact retention quota exceeded", 409);
+            }
+            await tx.run("INSERT INTO hv_memory_counters(agent_id,next_number) VALUES (?,1) ON CONFLICT DO NOTHING", actor.agentId);
+            const counter = (await tx.get("SELECT next_number FROM hv_memory_counters WHERE agent_id=?", actor.agentId));
+            const number = integer(counter.next_number, 1, Number.MAX_SAFE_INTEGER - 1, "next memory number");
+            await tx.run("UPDATE hv_memory_counters SET next_number=? WHERE agent_id=?", number + 1, actor.agentId);
+            await tx.run("INSERT INTO hv_memories(agent_id,number,kind,topic,instrument,interval,summary,content,payload,created_at,evidence_as_of,valid_until,producer_subagent_id,source_run_id,conversation_id,tool_task_id) VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?)", actor.agentId, number, kind, input.topic, input.instrument, input.interval, input.summary, input.content, JSON.stringify(input.payload), now, input.kind === "research" ? input.evidenceAsOf : null, deadline, actor.subagentId, actor.runId, actor.conversationId, actor.toolTaskId);
+            for (const link of links)
+                await tx.run("INSERT INTO hv_memory_links(agent_id,source_number,target_number,relation) VALUES (?,?,?,?)", actor.agentId, number, parseMemoryRef(link.ref), link.relation);
+            for (const id of input.artifactIds)
+                await tx.run("INSERT INTO hv_memory_artifacts(agent_id,memory_number,artifact_id) VALUES (?,?,?)", actor.agentId, number, id);
+            if (kind === "research")
+                await enqueueWorkerEvent(tx, actor.agentId, `research:${number}`, {
+                    intent: "evaluation", reason: "research", task: `Evaluate newly published research ${memoryRef(number)}. Read the full report and current account state; decide independently whether any action is warranted.`,
+                    callerSubagentId: actor.subagentId, callerRunId: actor.runId, researchRefs: [memoryRef(number)],
+                }, now);
+            return saveOperation(tx, actor, key, operation, hash, { ref: memoryRef(number), kind, createdAt: now, validUntil: deadline }, now);
+        });
+    }
+    async replacements(tx, agentId, numbers) {
+        if (!numbers.length)
+            return new Map();
+        // One bounded lookup per page, not a query per publication. Relationship
+        // history remains immutable; expose the latest direct ref for each kind.
+        const rows = await tx.all(`SELECT target_number,
+      max(CASE WHEN relation='corrects' THEN source_number END) AS corrected_by,
+      max(CASE WHEN relation='supersedes' THEN source_number END) AS superseded_by
+      FROM hv_memory_links WHERE agent_id=? AND target_number IN (${numbers.map(() => "?").join(",")})
+      AND relation IN ('corrects','supersedes') GROUP BY target_number`, agentId, ...numbers);
+        return new Map(rows.map((row) => [row.target_number, { correctedBy: row.corrected_by === null ? null : memoryRef(row.corrected_by), supersededBy: row.superseded_by === null ? null : memoryRef(row.superseded_by) }]));
+    }
+    async row(tx, agentId, number) {
+        const row = await tx.get(`SELECT *,${statusSql(this.clock())} AS status FROM hv_memories WHERE agent_id=? AND number=?`, agentId, number);
+        if (!row)
+            throw new AgentError("Memory not found in this Agent", 404);
+        return row;
+    }
+    async get(agentId, ref) {
+        const number = parseMemoryRef(ref);
+        return this.db.transaction(async (tx) => {
+            const row = await this.row(tx, agentId, number);
+            const links = await tx.all("SELECT target_number,relation FROM hv_memory_links WHERE agent_id=? AND source_number=? ORDER BY target_number,relation", agentId, number);
+            const artifacts = await tx.all("SELECT artifact_id FROM hv_memory_artifacts WHERE agent_id=? AND memory_number=? ORDER BY artifact_id", agentId, number);
+            const replacements = await this.replacements(tx, agentId, [number]);
+            return { ...metadata(row, replacements.get(number)), content: row.content, payload: JSON.parse(row.payload), links: links.map((link) => ({ ref: memoryRef(link.target_number), relation: link.relation })), artifactIds: artifacts.map((item) => item.artifact_id), conversationId: row.conversation_id, toolTaskId: row.tool_task_id };
+        });
+    }
+    async list(agentId, value = {}) {
+        const filter = fields(value, ["kind", "instrument", "topic", "interval", "producerSubagentId", "sourceRunId", "query", "status", "start", "end", "limit", "cursor"]);
+        const kind = filter.kind === undefined ? "" : choice(filter.kind, memoryKinds);
+        const coin = filter.instrument === undefined ? "" : instrument(filter.instrument);
+        const stream = filter.topic === undefined ? "" : topic(filter.topic);
+        const width = filter.interval === undefined ? "" : interval(filter.interval);
+        const producer = filter.producerSubagentId === undefined ? "" : text(filter.producerSubagentId, 100, "producer ID");
+        const run = filter.sourceRunId === undefined ? "" : text(filter.sourceRunId, 100, "run ID");
+        const query = filter.query === undefined ? "" : text(filter.query, 200, "search", true);
+        const status = filter.status === undefined ? "" : choice(filter.status, ["durable", "missing", "fresh", "stale", "retracted", "invalid_evidence"]);
+        const start = filter.start === undefined ? 0 : timestamp(filter.start), end = filter.end === undefined ? Number.MAX_SAFE_INTEGER : timestamp(filter.end);
+        if (end <= start)
+            throw new AgentError("Invalid memory time window");
+        const limit = filter.limit === undefined ? 25 : integer(filter.limit, 1, 50, "page size");
+        const cursor = filter.cursor == null ? null : fields(filter.cursor, ["createdAt", "ref"]);
+        const time = cursor ? timestamp(cursor.createdAt) : Number.MAX_SAFE_INTEGER;
+        const number = cursor ? parseMemoryRef(text(cursor.ref, 32, "cursor reference")) : Number.MAX_SAFE_INTEGER;
+        return this.db.transaction(async (tx) => {
+            const rows = await tx.all(`SELECT ${columns},${statusSql(this.clock())} AS status FROM hv_memories WHERE agent_id=? AND created_at>=? AND created_at<? AND (?='' OR status=?) AND (?='' OR kind=?) AND (?='' OR instrument=?) AND (?='' OR topic=?) AND (?='' OR interval=?) AND (?='' OR producer_subagent_id=?) AND (?='' OR source_run_id=?) AND (?='' OR instr(lower(summary),lower(?))>0) AND (created_at<? OR (created_at=? AND number<?)) ORDER BY created_at DESC,number DESC LIMIT ?`, agentId, start, end, status, status, kind, kind, coin, coin, stream, stream, width, width, producer, producer, run, run, query, query, time, time, number, limit + 1);
+            const page = rows.slice(0, limit), replacements = await this.replacements(tx, agentId, page.map((row) => row.number));
+            const items = page.map((row) => metadata(row, replacements.get(row.number))), last = items.at(-1);
+            return { items, nextCursor: rows.length > limit && last ? { createdAt: last.createdAt, ref: last.ref } : null };
+        });
+    }
+    /** Advisory current-research retrieval for caller-supplied stream requirements. */
+    tradingContext(agentId, coin, value) {
+        return this.db.transaction((tx) => this.tradingContextTx(tx, agentId, coin, value));
+    }
+    async tradingContextTx(tx, agentId, coin, value) {
+        instrument(coin);
+        const requirements = researchRequirements(value);
+        const now = timestamp(this.clock());
+        const items = [];
+        for (const requirement of requirements) {
+            // Select the latest BEFORE evaluating freshness: never resurrect older reports.
+            const row = await tx.get(`SELECT ${columns},${statusSql(now)} AS status FROM hv_memories WHERE agent_id=? AND kind='research' AND instrument=? AND topic=? AND interval=? AND producer_subagent_id=? ORDER BY number DESC LIMIT 1`, agentId, coin, requirement.topic, requirement.interval, requirement.subagentId);
+            const status = (row?.status ?? "missing");
+            const consumerValidUntil = row ? Math.min(row.valid_until, row.evidence_as_of + requirement.maxAgeSeconds * 1000) : null;
+            const consumerStatus = status === "fresh" && now >= consumerValidUntil ? "stale" : status;
+            items.push({ producerSubagentId: requirement.subagentId, topic: requirement.topic, interval: requirement.interval, ref: row ? memoryRef(row.number) : null, status, evidenceAsOf: row?.evidence_as_of ?? null, validUntil: row?.valid_until ?? null, maxAgeSeconds: requirement.maxAgeSeconds, consumerStatus, consumerValidUntil, summary: consumerStatus === "fresh" ? row.summary : null });
+        }
+        const replacements = await this.replacements(tx, agentId, items.flatMap((item) => item.ref ? [parseMemoryRef(item.ref)] : []));
+        // Publication age and caller-specific age requirements are separate. Neither
+        // freshness nor absence of a replacement implies suitability for a trade.
+        return { observedAt: now, instrument: coin, requirements: items.map((item) => ({ ...item, correctedBy: item.ref ? replacements.get(parseMemoryRef(item.ref))?.correctedBy ?? null : null, supersededBy: item.ref ? replacements.get(parseMemoryRef(item.ref))?.supersededBy ?? null : null })) };
+    }
+}

package/dist/memory/operations.js

@@ -0,0 +1,46 @@
+import { createHash } from "node:crypto";
+import { AgentError } from "../agents/agent-input.js";
+import { canonical } from "../canonical.js";
+import { text } from "./validation.js";
+export function requestHash(actor, operation, input) {
+    return createHash("sha256").update(canonical({ actor, operation, input })).digest("hex");
+}
+export async function operationReplay(tx, actor, key, kind, hash) {
+    text(key, 200, "operation key");
+    const row = await tx.get("SELECT request_hash,operation_kind,result FROM hv_memory_operations WHERE agent_id=? AND operation_key=?", actor.agentId, key);
+    if (!row)
+        return undefined;
+    if (row.request_hash !== hash || row.operation_kind !== kind)
+        throw new AgentError("Operation key reused with different arguments or actor", 409);
+    return JSON.parse(row.result);
+}
+export async function saveOperation(tx, actor, key, kind, hash, result, now) {
+    await tx.run("INSERT INTO hv_memory_operations(agent_id,operation_key,operation_kind,request_hash,result,created_at) VALUES (?,?,?,?,?,?)", actor.agentId, key, kind, hash, JSON.stringify(result), now);
+    return result;
+}
+/** Call after receipt lookup: successful effects remain replayable after their run finished. */
+export async function assertActiveActor(tx, actor) {
+    const owner = await tx.get("SELECT user_id,state,enabled FROM hv_agents WHERE id=?", actor.agentId);
+    if (!owner)
+        throw new AgentError("Agent not found", 404);
+    if (owner.state === "stopping" || owner.state === "stopped")
+        throw new AgentError("Agent is being deleted", 409);
+    if (actor.userId && actor.userId !== owner.user_id)
+        throw new AgentError("Agent not found", 404);
+    if (actor.subagentId && owner.enabled !== 1)
+        throw new AgentError("Agent is disabled", 409);
+    if (actor.runId) {
+        if (!actor.subagentId)
+            throw new AgentError("Missing run producer", 403);
+        const run = await tx.get("SELECT status,conversation_id FROM hv_subagent_runs WHERE agent_id=? AND id=? AND subagent_id=?", actor.agentId, actor.runId, actor.subagentId);
+        if (!run || !["queued", "running"].includes(run.status) || (run.conversation_id !== null && run.conversation_id !== actor.conversationId))
+            throw new AgentError("Run is no longer active or does not match execution", 409);
+    }
+    else if (actor.subagentId) {
+        const root = await tx.get("SELECT id FROM hv_subagents WHERE agent_id=? AND id=? AND kind='orchestrator' AND archived=0", actor.agentId, actor.subagentId);
+        if (!root)
+            throw new AgentError("Invalid root producer", 403);
+    }
+    else if (!actor.userId)
+        throw new AgentError("Unverified actor", 403);
+}

package/dist/memory/tool-schemas.js

@@ -0,0 +1,44 @@
+import { Type } from "@earendil-works/pi-ai";
+import { topicPattern } from "./memory-contracts.js";
+const options = { additionalProperties: false };
+const str = (maxLength, minLength = 0) => Type.String({ minLength, maxLength });
+const time = Type.Integer({ minimum: 0, maximum: Number.MAX_SAFE_INTEGER });
+const nullable = (schema) => Type.Union([schema, Type.Null()]);
+const enumeration = (values) => Type.Union(values.map((value) => Type.Literal(value)), { description: `Exactly one of: ${values.map((value) => JSON.stringify(value)).join(", ")}.` });
+export const Ref = Type.String({ pattern: "^m[1-9][0-9]*$", maxLength: 17 });
+const Topic = Type.String({ pattern: topicPattern.source, minLength: 1, maxLength: 64, description: "Lowercase topic identifier, e.g. trend_setup or trade_decision. Start with a letter; use only lowercase letters, numbers and underscores (1–64 characters). No spaces or hyphens." });
+const refs = Type.Array(Ref, { maxItems: 20 });
+const texts = Type.Array(str(1000, 1), { maxItems: 20 });
+export const Scope = Type.Union([Type.Object({ kind: Type.Literal("agent") }, options), Type.Object({ kind: Type.Literal("worker"), subagentId: str(100, 1) }, options)]);
+const relation = enumeration(["based_on", "corrects", "supersedes", "reviews"]);
+const coverage = enumeration(["complete", "incomplete", "unknown"]);
+export const ResearchPayloadSchema = Type.Record(Type.String(), Type.Unknown(), { description: "Optional free-form JSON data (maximum 16 KiB). No required keys, labels or analytical enums. The full report belongs in content." });
+const payloadVersion = Type.Literal(1, { description: "Always the number 1: payload schema version, NOT a decision count or revision number. Keep 1 for every new publication and follow-up." });
+export const DecisionPayloadSchema = Type.Object({ version: payloadVersion, action: enumeration(["enter", "hold", "skip", "reduce", "close", "protect"]), direction: Type.Union([enumeration(["long", "short"]), Type.Null()]), reason: str(4000, 1), researchRefs: { ...refs, description: "Exact research refs actually used for this decision. Use [] when none were used, including a direct operator/chart-based request; never invent refs." }, plan: str(4000) }, options);
+export const ReviewPayloadSchema = Type.Object({ version: payloadVersion, start: time, end: time, coverage, limitations: texts, findings: texts, recommendations: texts, memoryRefs: refs }, options);
+const link = Type.Object({ ref: Ref, relation }, options);
+const base = { topic: Topic, instrument: Type.Optional(nullable(str(32, 1))), interval: Type.Optional(nullable(str(8, 1))), summary: Type.String({ minLength: 1, maxLength: 500, description: "Short, descriptive title for memory listings, ideally 5–10 words. Capture the main finding in plain language, not a miniature report. Do not include prices, statistics, indicator values or timestamps; put those details in content. Avoid repeating instrument and interval metadata. Example: Bounce fails as bearish momentum returns." }), content: Type.String({ minLength: 1, maxLength: 16000, description: "Standalone report for another agent to interpret. Plain text or Markdown; no required headings, analytical fields or classifications. Include relevant evidence, uncertainty and limitations in your own words." }), artifactIds: Type.Optional(Type.Array(str(36, 36), { maxItems: 20 })), links: Type.Optional(Type.Array(link, { maxItems: 20 })) };
+export const ResearchInputSchema = Type.Object({ ...base, instrument: str(32, 1), interval: Type.String({ minLength: 1, maxLength: 8, description: "Primary decision timeframe (e.g. 15m or 1d), not the worker schedule or the longest contextual timeframe mentioned in the report." }), evidenceAsOf: Type.Integer({ minimum: 0, maximum: Number.MAX_SAFE_INTEGER, description: "Exclusive closed-candle end for the primary decision interval, as an absolute UTC Unix timestamp in MILLISECONDS, not seconds or publication time. In Code Mode, reuse the verified request end variable after checking returned candles reach that boundary; when deriving from a candle open time in seconds, use last.time * 1000 + intervalMs. Respect any assignment endMs ceiling. Must be interval-aligned and not in the future. Never hand-copy a computed timestamp into another call: await tools.publish_research({...report, evidenceAsOf: endMs}) in the same script, or store/load endMs between scripts. Do not advance old evidence to the current boundary." }), requestedValidUntil: Type.Optional(Type.Integer({ minimum: 0, maximum: Number.MAX_SAFE_INTEGER, description: "Optional absolute Unix timestamp in UTC milliseconds, NOT a duration; must be greater than evidenceAsOf. Calculate in code: requestedValidUntil = evidenceAsOf + 6 * 60 * 60 * 1000 for six hours, never pass 21600000 alone. Pass the computed variable directly to await tools.publish_research; never manually retype the numeric result. Omit for a two-candle-interval lifetime; explicitly request shorter or longer when justified by the analysis, explaining unusual lifetimes in content. The host caps all lifetimes at seven days from evidence. Corrections cannot extend the original deadline." })), payload: Type.Optional(ResearchPayloadSchema) }, options);
+export const DecisionInputSchema = Type.Object({ ...base, payload: DecisionPayloadSchema }, options);
+export const ReviewInputSchema = Type.Object({ ...base, payload: ReviewPayloadSchema }, options);
+const kind = enumeration(["research", "decision", "review"]);
+const replacements = { correctedBy: Type.Union([Type.String({ pattern: "^m[1-9][0-9]*$", description: "Latest direct correction ref, if any. Read it for corrected evidence and any subsequent replacement; the original remains historical even if recent." }), Type.Null()]), supersededBy: Type.Union([Type.String({ pattern: "^m[1-9][0-9]*$", description: "Latest direct superseding ref, if any. Read it for the replacement assessment and any subsequent replacement; freshness alone does not mean this report is current." }), Type.Null()]) };
+const metadata = { ...replacements, ref: Ref, status: Type.String({ description: "Publication evidence-age status, independent of whether correctedBy or supersededBy replaces this assessment." }), kind, topic: Topic, instrument: nullable(str(32)), interval: nullable(str(8)), summary: str(500), createdAt: time, evidenceAsOf: nullable(time), validUntil: nullable(time), producerSubagentId: nullable(str(100)), sourceRunId: nullable(str(100)), retractedAt: nullable(time), retractionReason: nullable(str(1000)) };
+export const MetadataSchema = Type.Object(metadata, options);
+export const PublicationResultSchema = Type.Object({ ref: Ref, kind, createdAt: time, validUntil: nullable(time) }, options);
+export const MemoryDetailSchema = Type.Object({ ...metadata, content: str(16000), payload: Type.Union([ResearchPayloadSchema, DecisionPayloadSchema, ReviewPayloadSchema]), links: Type.Array(link, { maxItems: 20 }), artifactIds: Type.Array(str(36)) }, options);
+const cursor = Type.Object({ createdAt: time, ref: Ref }, options);
+export const MemoryListInputSchema = Type.Object({ kind: Type.Optional(kind), instrument: Type.Optional(str(32)), topic: Type.Optional(Topic), interval: Type.Optional(str(8)), producerSubagentId: Type.Optional(str(100)), sourceRunId: Type.Optional(str(100)), query: Type.Optional(str(200)), status: Type.Optional(Type.String()), start: Type.Optional(time), end: Type.Optional(time), limit: Type.Optional(Type.Integer({ minimum: 1, maximum: 50 })), cursor: Type.Optional(cursor) }, options);
+export const MemoryListSchema = Type.Object({ items: Type.Array(MetadataSchema, { maxItems: 50 }), nextCursor: Type.Union([cursor, Type.Null()]) }, options);
+const researchStatus = enumeration(["missing", "fresh", "stale", "retracted", "invalid_evidence"]);
+export const TradingContextSchema = Type.Object({ observedAt: time, instrument: str(32), requirements: Type.Array(Type.Object({ ...replacements, producerSubagentId: str(100), topic: Topic, interval: str(8), ref: nullable(Ref), status: { ...researchStatus, description: "Publication status, consistent with get_memory/list_memories; replacement standing is separate." }, evidenceAsOf: nullable(time), validUntil: { ...nullable(time), description: "Accepted publication deadline, consistent with get_memory/list_memories." }, maxAgeSeconds: time, consumerStatus: { ...researchStatus, description: "Freshness under this caller's maxAgeSeconds as well as the publication deadline. May be stale while publication status is fresh." }, consumerValidUntil: { ...nullable(time), description: "Earlier of the publication deadline and evidenceAsOf plus caller maxAgeSeconds." }, summary: nullable(str(500)) }, options), { maxItems: 20 }) }, options);
+export const TradingContextInputSchema = Type.Object({ instrument: str(32), streams: Type.Optional(Type.Array(Type.Object({ subagentId: str(100), topic: Topic, interval: str(8), maxAgeSeconds: time }, options), { maxItems: 20 })) }, options);
+export const InsightMutationResultSchema = Type.Object({ scope: Scope, version: time }, options);
+const insightBase = { scope: Scope, reason: str(1000, 1), evidenceRefs: Type.Optional(refs) };
+export const AppendInsightSchema = Type.Object({ ...insightBase, content: str(2000, 1) }, options);
+export const ReplaceInsightSchema = Type.Object({ ...insightBase, content: str(8000), expectedVersion: time }, options);
+const snapshot = { scope: Scope, version: time, content: str(8000) };
+const revisionMeta = { scope: Scope, version: time, operation: enumeration(["append", "replace"]), reason: str(1000), createdAt: time, userId: nullable(str(100)), producerSubagentId: nullable(str(100)), sourceRunId: nullable(str(100)) };
+export const InsightReadInputSchema = Type.Object({ scope: Scope, version: Type.Optional(time), history: Type.Optional(Type.Boolean()), beforeVersion: Type.Optional(time) }, options);
+export const FillAuditSchema = Type.Object({ items: Type.Array(Type.Object({ fillId: Type.String(), time, exchangeOid: nullable(Type.String()), requestId: nullable(Type.String()), decisionRef: nullable(Ref) }), { maxItems: 50 }), next: Type.Union([Type.Object({ time, id: Type.String() }), Type.Null()]), coverage: Type.String() });
+export const InsightReadSchema = Type.Union([Type.Object(snapshot, options), Type.Object({ ...snapshot, ...revisionMeta, evidenceRefs: Type.Array(Ref) }, options), Type.Object({ items: Type.Array(Type.Object(revisionMeta, options), { maxItems: 25 }), nextBeforeVersion: nullable(time) }, options)]);

package/dist/memory/validation.js

@@ -0,0 +1,42 @@
+import { AgentError } from "../agents/agent-input.js";
+export function object(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        throw new AgentError("Expected an object");
+    return value;
+}
+export function fields(value, keys) {
+    const row = object(value);
+    if (Object.keys(row).some((key) => !keys.includes(key)))
+        throw new AgentError("Unknown field; provenance and authority are host-owned");
+    return row;
+}
+export function text(value, max, label, empty = false) {
+    if (typeof value !== "string" || value.length > max || (!empty && !value.trim()))
+        throw new AgentError(`Invalid ${label} (maximum ${max} characters)`);
+    return value.trim();
+}
+export function integer(value, min, max, label) {
+    if (typeof value !== "number" || !Number.isSafeInteger(value) || value < min || value > max)
+        throw new AgentError(`Invalid ${label}`);
+    return value;
+}
+export function choice(value, options) {
+    if (typeof value !== "string" || !options.includes(value))
+        throw new AgentError(`Expected ${options.join(" / ")}`);
+    return value;
+}
+export function array(value, max, parse) {
+    if (!Array.isArray(value) || value.length > max)
+        throw new AgentError(`Expected at most ${max} items`);
+    return value.map(parse);
+}
+export function unique(values) {
+    if (new Set(values).size !== values.length)
+        throw new AgentError("Duplicate values are not allowed");
+    return values;
+}
+export function positiveDecimal(value) {
+    if (typeof value !== "string" || value.length > 80 || !/^(0|[1-9][0-9]*)(\.[0-9]+)?$/.test(value) || value.trim() !== value || !/[1-9]/.test(value))
+        throw new AgentError("Expected an exact positive decimal string");
+    return value;
+}

package/dist/notifications/contracts.js

@@ -0,0 +1 @@
+export {};

package/dist/notifications/delivery.js

@@ -0,0 +1,11 @@
+export class NotificationDeliveryError extends Error {
+    permanent;
+    retryAfterMs;
+    suppressed;
+    constructor(message, permanent = false, retryAfterMs, suppressed = false) {
+        super(message);
+        this.permanent = permanent;
+        this.retryAfterMs = retryAfterMs;
+        this.suppressed = suppressed;
+    }
+}

package/dist/notifications/durable-extension.js

@@ -0,0 +1,20 @@
+import { Type } from "@earendil-works/pi-ai";
+import { defineExtension, defineTool, section } from "@earendil-works/pi-durable";
+import { jsonResult } from "../research/tool-response.js";
+export function createNotificationExtension(agentId, notifications, execution) {
+    return defineExtension({
+        name: "notifications",
+        tools: [defineTool({
+                name: "send_notification",
+                description: "Send a concise user-facing notification to this Agent's web history and linked Telegram chat. Returns queued (not proof of Telegram delivery) or disabled. Backend order submission/fill notifications are automatic when enabled; do not duplicate them. Do not include credentials or secrets. Cite full review/report references in the body where useful. This is one-way, not a question/approval tool.",
+                parameters: Type.Object({
+                    title: Type.String({ minLength: 1, maxLength: 200 }), body: Type.String({ minLength: 1, maxLength: 12000 }),
+                    severity: Type.Optional(Type.Union([Type.Literal("info"), Type.Literal("warning"), Type.Literal("error")])),
+                }, { additionalProperties: false }),
+                structuredOutputSchema: Type.Union([Type.Object({ status: Type.Literal("queued"), id: Type.String() }), Type.Object({ status: Type.Literal("disabled") })]),
+                replay: "safe", executionMode: "sequential",
+                execute: async (args, api, context) => jsonResult(await notifications.sendFromTool((await execution.resolve(agentId, api, context)).actor, args, execution)),
+            })],
+        sections: [section("notifications", () => "send_notification is a one-way message to the user, not permission to trade or an interactive question. Queued means stored, not delivered or read. If disabled, continue the assignment without retrying or working around the setting. Do not duplicate automatic order submission/fill notifications. After a review is published and intended insight edits finish, send one crafted summary with the review reference, exact window/coverage, findings, actual changes versus recommendations, and unresolved limitations. Notification failures must not cause an exchange action to be repeated.")],
+    });
+}