@assemblyline-agents/runtime 0.1.0

package/dist/storage.js

@@ -0,0 +1,752 @@
+import { createHash, randomUUID } from "node:crypto";
+import { closeSync, existsSync, fsyncSync, mkdirSync, mkdtempSync, openSync, readFileSync, renameSync, writeFileSync, writeSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join, resolve, sep } from "node:path";
+import { normalizeDeliveryRecord } from "./delivery-queue.js";
+import { InMemoryConversationStore, InMemoryConversationTurnStore, InMemoryFileIndexStore, InMemoryMemoryStateStore, InMemoryRunStore, InMemoryRuntimeSettingsStore, InMemorySandboxSessionStore, InMemoryScheduleStateStore, InMemoryUsageStore, memoryBodyText, memoryKey, memoryEmbeddingKey, memoryScopeMatches, memorySnippet, normalizeMemoryPath, positiveLimit } from "./state-stores.js";
+import { normalizeStoredUsageRecord } from "./usage-records.js";
+export { applySandboxSyncJobPatch, cosineSimilarity, createSandboxSyncJobRecord, isSandboxSyncJobDue, memoryBodyText, memoryEmbeddingKey, memoryKey, memoryScopeMatches, memorySnippet, normalizeMemoryPath, positiveLimit, sandboxSyncRetryDelayMs } from "./state-stores.js";
+function timestamp() {
+    return new Date().toISOString();
+}
+function stringValue(value) {
+    return typeof value === "string" ? value.trim() : "";
+}
+/**
+ * Full in-memory `StateAdapter`, composed from the per-facet in-memory
+ * stores in `state-stores.ts`. Public name and behavior are unchanged; the
+ * facets share this adapter's `persist()` hook so `FileStateAdapter` keeps
+ * snapshotting everything on every write.
+ */
+export class InMemoryStateAdapter {
+    runStore = new InMemoryRunStore(() => this.persist());
+    conversationStore = new InMemoryConversationStore(() => this.persist());
+    conversationTurnStore = new InMemoryConversationTurnStore(() => this.persist());
+    scheduleStateStore = new InMemoryScheduleStateStore(() => this.persist());
+    fileIndexStore = new InMemoryFileIndexStore(() => this.persist());
+    usageStore = new InMemoryUsageStore(() => this.persist());
+    sandboxStore = new InMemorySandboxSessionStore(() => this.persist());
+    memoryStateStore = new InMemoryMemoryStateStore(() => this.persist());
+    runtimeSettingsStore = new InMemoryRuntimeSettingsStore(() => this.persist());
+    createRun(input) {
+        return this.runStore.createRun(input);
+    }
+    touchRun(id) {
+        return this.runStore.touchRun(id);
+    }
+    requestRunControl(id, intent) {
+        return this.runStore.requestRunControl(id, intent);
+    }
+    settleRunControl(id) {
+        return this.runStore.settleRunControl(id);
+    }
+    updateRun(id, patch) {
+        return this.runStore.updateRun(id, patch);
+    }
+    getRun(id) {
+        return this.runStore.getRun(id);
+    }
+    listRuns() {
+        return this.runStore.listRuns();
+    }
+    appendEvent(runId, type, data) {
+        return this.runStore.appendEvent(runId, type, data);
+    }
+    listEvents(runId) {
+        return this.runStore.listEvents(runId);
+    }
+    createToolCall(input) {
+        return this.runStore.createToolCall(input);
+    }
+    updateToolCall(id, patch) {
+        return this.runStore.updateToolCall(id, patch);
+    }
+    listToolCalls(runId) {
+        return this.runStore.listToolCalls(runId);
+    }
+    createCheckpoint(input) {
+        return this.runStore.createCheckpoint(input);
+    }
+    listCheckpoints(runId) {
+        return this.runStore.listCheckpoints(runId);
+    }
+    compactCheckpoints(options) {
+        return this.runStore.compactCheckpoints(options);
+    }
+    createDelivery(input) {
+        return this.runStore.createDelivery(input);
+    }
+    updateDelivery(id, patch) {
+        return this.runStore.updateDelivery(id, patch);
+    }
+    listDeliveries(runId) {
+        return this.runStore.listDeliveries(runId);
+    }
+    leaseDueDeliveries(options) {
+        return this.runStore.leaseDueDeliveries(options);
+    }
+    completeDeliverySend(id, leaseToken, patch) {
+        return this.runStore.completeDeliverySend(id, leaseToken, patch);
+    }
+    failDeliverySend(id, leaseToken, failure) {
+        return this.runStore.failDeliverySend(id, leaseToken, failure);
+    }
+    recoverExpiredDeliveries(now) {
+        return this.runStore.recoverExpiredDeliveries(now);
+    }
+    reserveIdempotencyKey(scope, key, ownerId) {
+        return this.runStore.reserveIdempotencyKey(scope, key, ownerId);
+    }
+    upsertConversation(input) {
+        return this.conversationStore.upsertConversation(input);
+    }
+    getConversation(id) {
+        return this.conversationStore.getConversation(id);
+    }
+    listConversations(input) {
+        return this.conversationStore.listConversations(input);
+    }
+    updateConversation(id, patch) {
+        return this.conversationStore.updateConversation(id, patch);
+    }
+    listRecentConversationsBySubject(input) {
+        return this.conversationStore.listRecentConversationsBySubject(input);
+    }
+    appendMessage(input) {
+        return this.conversationStore.appendMessage(input);
+    }
+    listRecentMessages(conversationId, limit) {
+        return this.conversationStore.listRecentMessages(conversationId, limit);
+    }
+    listMessages(input) {
+        return this.conversationStore.listMessages(input);
+    }
+    enqueueConversationTurn(input) {
+        return this.conversationTurnStore.enqueueConversationTurn(input);
+    }
+    leaseNextConversationTurn(options) {
+        return this.conversationTurnStore.leaseNextConversationTurn(options);
+    }
+    attachConversationTurnRun(id, leaseToken, runId) {
+        return this.conversationTurnStore.attachConversationTurnRun(id, leaseToken, runId);
+    }
+    settleConversationTurn(id, leaseToken, status, options) {
+        return this.conversationTurnStore.settleConversationTurn(id, leaseToken, status, options);
+    }
+    settleConversationTurnByRunId(runId, status, options) {
+        return this.conversationTurnStore.settleConversationTurnByRunId(runId, status, options);
+    }
+    retryConversationTurn(id, leaseToken, error) {
+        return this.conversationTurnStore.retryConversationTurn(id, leaseToken, error);
+    }
+    recoverExpiredConversationTurns(now) {
+        return this.conversationTurnStore.recoverExpiredConversationTurns(now);
+    }
+    listConversationTurns(options) {
+        return this.conversationTurnStore.listConversationTurns(options);
+    }
+    registerSchedule(input) {
+        return this.scheduleStateStore.registerSchedule(input);
+    }
+    recordScheduleRun(input) {
+        return this.scheduleStateStore.recordScheduleRun(input);
+    }
+    recordFileIndex(input) {
+        return this.fileIndexStore.recordFileIndex(input);
+    }
+    listFileIndexes(runId) {
+        return this.fileIndexStore.listFileIndexes(runId);
+    }
+    recordUsage(input) {
+        return this.usageStore.recordUsage(input);
+    }
+    listUsage(runId) {
+        return this.usageStore.listUsage(runId);
+    }
+    queryUsage(query) {
+        return this.usageStore.queryUsage(query);
+    }
+    summarizeUsage(query) {
+        return this.usageStore.summarizeUsage(query);
+    }
+    recordSandboxSnapshot(input) {
+        return this.sandboxStore.recordSandboxSnapshot(input);
+    }
+    upsertSandboxSession(input) {
+        return this.sandboxStore.upsertSandboxSession(input);
+    }
+    getSandboxSession(sessionKey) {
+        return this.sandboxStore.getSandboxSession(sessionKey);
+    }
+    listSandboxSessions(options) {
+        return this.sandboxStore.listSandboxSessions(options);
+    }
+    updateSandboxSession(sessionKey, patch) {
+        return this.sandboxStore.updateSandboxSession(sessionKey, patch);
+    }
+    createSandboxSyncJob(input) {
+        return this.sandboxStore.createSandboxSyncJob(input);
+    }
+    enqueueSandboxSyncJob(input) {
+        return this.sandboxStore.enqueueSandboxSyncJob(input);
+    }
+    updateSandboxSyncJob(id, patch) {
+        return this.sandboxStore.updateSandboxSyncJob(id, patch);
+    }
+    listSandboxSyncJobs(runId) {
+        return this.sandboxStore.listSandboxSyncJobs(runId);
+    }
+    leaseSandboxSyncJobs(options) {
+        return this.sandboxStore.leaseSandboxSyncJobs(options);
+    }
+    completeSandboxSyncJob(id, leaseToken, patch) {
+        return this.sandboxStore.completeSandboxSyncJob(id, leaseToken, patch);
+    }
+    failSandboxSyncJob(id, leaseToken, failure) {
+        return this.sandboxStore.failSandboxSyncJob(id, leaseToken, failure);
+    }
+    recoverExpiredSandboxSyncJobs(now) {
+        return this.sandboxStore.recoverExpiredSandboxSyncJobs(now);
+    }
+    listMemoryDocuments(scope, input) {
+        return this.memoryStateStore.listMemoryDocuments(scope, input);
+    }
+    supportsMemoryEmbeddings() {
+        return this.memoryStateStore.supportsMemoryEmbeddings();
+    }
+    getMemoryDocument(scope, path) {
+        return this.memoryStateStore.getMemoryDocument(scope, path);
+    }
+    upsertMemoryDocument(document) {
+        return this.memoryStateStore.upsertMemoryDocument(document);
+    }
+    deleteMemoryDocument(scope, path) {
+        return this.memoryStateStore.deleteMemoryDocument(scope, path);
+    }
+    listMemoryDocumentsNeedingEmbeddings(scope, options) {
+        return this.memoryStateStore.listMemoryDocumentsNeedingEmbeddings(scope, options);
+    }
+    upsertMemoryEmbedding(input) {
+        return this.memoryStateStore.upsertMemoryEmbedding(input);
+    }
+    searchMemoryEmbeddings(scope, input, embedding, options) {
+        return this.memoryStateStore.searchMemoryEmbeddings(scope, input, embedding, options);
+    }
+    markMemoryEmbeddingsStale(scope, path, currentSha256) {
+        return this.memoryStateStore.markMemoryEmbeddingsStale(scope, path, currentSha256);
+    }
+    getSetting(scope, key) {
+        return this.runtimeSettingsStore.getSetting(scope, key);
+    }
+    setSetting(scope, key, value) {
+        return this.runtimeSettingsStore.setSetting(scope, key, value);
+    }
+    appendRuntimeControlEvent(scope, type, data) {
+        return this.runtimeSettingsStore.appendRuntimeControlEvent(scope, type, data);
+    }
+    listRuntimeControlEvents(scope) {
+        return this.runtimeSettingsStore.listRuntimeControlEvents(scope);
+    }
+    async persist() {
+        return;
+    }
+}
+/** Temp-file + fsync + atomic-rename write so a crash never tears the target file. */
+function writeAtomic(path, tempPath, contents) {
+    const fd = openSync(tempPath, "w");
+    try {
+        writeSync(fd, contents);
+        fsyncSync(fd);
+    }
+    finally {
+        closeSync(fd);
+    }
+    renameSync(tempPath, path);
+}
+export class FileStateAdapter extends InMemoryStateAdapter {
+    path;
+    constructor(path) {
+        super();
+        this.path = path;
+        this.load();
+    }
+    async persist() {
+        mkdirSync(dirname(this.path), { recursive: true });
+        // Crash-safe write: serialize to a temp file, fsync, then atomically
+        // rename over the target so a crash mid-write can never leave a torn,
+        // unparseable state file behind.
+        const tempPath = `${this.path}.tmp-${process.pid}`;
+        writeAtomic(this.path, tempPath, JSON.stringify({
+            runs: [...this.runStore.runs.values()],
+            events: this.runStore.events,
+            toolCalls: [...this.runStore.toolCalls.values()],
+            checkpoints: this.runStore.checkpoints,
+            deliveries: [...this.runStore.deliveries.values()],
+            conversations: [...this.conversationStore.conversations.values()],
+            messages: this.conversationStore.messages,
+            conversationTurns: [...this.conversationTurnStore.turns.values()],
+            schedules: [...this.scheduleStateStore.schedules.values()],
+            scheduleRuns: this.scheduleStateStore.scheduleRuns,
+            fileIndexes: this.fileIndexStore.fileIndexes,
+            usageRecords: this.usageStore.usageRecords,
+            sandboxSnapshots: this.sandboxStore.sandboxSnapshots,
+            sandboxSessions: [...this.sandboxStore.sandboxSessions.values()],
+            sandboxSyncJobs: [...this.sandboxStore.sandboxSyncJobs.values()],
+            memoryDocuments: [...this.memoryStateStore.memoryDocuments.values()],
+            memoryEmbeddings: [...this.memoryStateStore.memoryEmbeddings.values()],
+            runtimeSettings: [...this.runtimeSettingsStore.settings.values()],
+            runtimeControlEvents: this.runtimeSettingsStore.controlEvents,
+            idempotency: [...this.runStore.idempotency.values()]
+        }, null, 2));
+    }
+    load() {
+        if (!existsSync(this.path))
+            return;
+        const raw = readFileSync(this.path, "utf8");
+        let data;
+        try {
+            data = JSON.parse(raw);
+        }
+        catch {
+            // A torn write from a pre-atomic-rename version of this adapter (or
+            // external corruption) must not brick the host: preserve the bytes for
+            // inspection and start from an empty state instead of throwing.
+            const backupPath = `${this.path}.corrupt-${Date.now()}`;
+            writeFileSync(backupPath, raw);
+            process.emitWarning(`OpenEve file state at ${this.path} was unreadable; backed up to ${backupPath} and starting fresh.`);
+            return;
+        }
+        const parsed = data;
+        for (const run of parsed.runs ?? [])
+            this.runStore.runs.set(run.id, run);
+        this.runStore.events = parsed.events ?? [];
+        for (const toolCall of parsed.toolCalls ?? [])
+            this.runStore.toolCalls.set(toolCall.id, toolCall);
+        this.runStore.checkpoints = parsed.checkpoints ?? [];
+        for (const delivery of parsed.deliveries ?? []) {
+            const normalized = normalizeDeliveryRecord(delivery);
+            this.runStore.deliveries.set(normalized.id, normalized);
+        }
+        for (const conversation of parsed.conversations ?? [])
+            this.conversationStore.conversations.set(conversation.id, conversation);
+        this.conversationStore.messages = parsed.messages ?? [];
+        for (const turn of parsed.conversationTurns ?? []) {
+            this.conversationTurnStore.turns.set(turn.id, turn);
+        }
+        for (const schedule of parsed.schedules ?? [])
+            this.scheduleStateStore.schedules.set(schedule.id, schedule);
+        this.scheduleStateStore.scheduleRuns = parsed.scheduleRuns ?? [];
+        this.fileIndexStore.fileIndexes = parsed.fileIndexes ?? [];
+        this.usageStore.usageRecords = (parsed.usageRecords ?? [])
+            .map(normalizeStoredUsageRecord)
+            .filter((record) => record !== undefined);
+        this.sandboxStore.sandboxSnapshots = parsed.sandboxSnapshots ?? [];
+        for (const session of parsed.sandboxSessions ?? [])
+            this.sandboxStore.sandboxSessions.set(session.sessionKey, session);
+        for (const job of parsed.sandboxSyncJobs ?? []) {
+            const normalized = normalizeSandboxSyncJobRecord(job);
+            this.sandboxStore.sandboxSyncJobs.set(normalized.id, normalized);
+        }
+        for (const document of parsed.memoryDocuments ?? [])
+            this.memoryStateStore.memoryDocuments.set(memoryKey(document.scope, document.path), document);
+        for (const embedding of parsed.memoryEmbeddings ?? []) {
+            this.memoryStateStore.memoryEmbeddings.set(memoryEmbeddingKey(embedding.scope, embedding.path, embedding.model), embedding);
+        }
+        for (const setting of parsed.runtimeSettings ?? []) {
+            this.runtimeSettingsStore.settings.set(`${setting.scope}:${setting.key}`, setting);
+        }
+        this.runtimeSettingsStore.controlEvents = parsed.runtimeControlEvents ?? [];
+        this.runStore.idempotency = new Set(parsed.idempotency ?? []);
+    }
+}
+export class LocalBlobAdapter {
+    root;
+    constructor(root = mkdtempSync(join(tmpdir(), "openeve-blob-"))) {
+        this.root = root;
+    }
+    /**
+     * Resolve a blob key to an absolute path that is guaranteed to stay inside the
+     * blob root. Stripping leading slashes alone leaves `..` segments intact, so a
+     * key like `../../etc/passwd` (e.g. a forged attachment `blobKey`) would
+     * otherwise escape the root for both reads and writes.
+     */
+    resolveKey(key) {
+        const rootResolved = resolve(this.root);
+        const target = resolve(rootResolved, key.replace(/^\/+/, ""));
+        if (target !== rootResolved && !target.startsWith(rootResolved + sep)) {
+            throw new Error(`Blob key escapes the storage root: ${key}`);
+        }
+        return target;
+    }
+    async put(key, value, contentTypeOrOptions) {
+        const options = normalizeBlobPutOptions(contentTypeOrOptions);
+        const bytes = typeof value === "string" ? Buffer.from(value) : Buffer.from(value);
+        const safeKey = key.replace(/^\/+/, "");
+        const path = this.resolveKey(key);
+        mkdirSync(dirname(path), { recursive: true });
+        writeFileSync(path, bytes);
+        const record = {
+            id: randomUUID(),
+            key: safeKey,
+            uri: path,
+            sha256: createHash("sha256").update(bytes).digest("hex"),
+            size: bytes.byteLength
+        };
+        if (options.contentType)
+            record.contentType = options.contentType;
+        if (options.visibility)
+            record.visibility = options.visibility;
+        return record;
+    }
+    async get(key) {
+        const path = this.resolveKey(key);
+        if (!existsSync(path))
+            return undefined;
+        return readFileSync(path);
+    }
+}
+function normalizeBlobPutOptions(contentTypeOrOptions) {
+    if (typeof contentTypeOrOptions === "string")
+        return { contentType: contentTypeOrOptions, visibility: "private" };
+    const options = { visibility: contentTypeOrOptions?.visibility ?? "private" };
+    if (contentTypeOrOptions?.contentType)
+        options.contentType = contentTypeOrOptions.contentType;
+    return options;
+}
+export class InMemoryMemoryStore {
+    documents = new Map();
+    async list(scope, input = {}) {
+        const prefix = normalizeMemoryPath(input.pathPrefix ?? "");
+        const limit = positiveLimit(input.limit, 50);
+        return [...this.documents.values()]
+            .filter((document) => memoryScopeMatches(scope, document.scope))
+            .filter((document) => !prefix || document.path.startsWith(prefix))
+            .sort((a, b) => b.updatedAt.localeCompare(a.updatedAt))
+            .slice(0, limit);
+    }
+    async search(scope, input) {
+        const prefix = normalizeMemoryPath(input.pathPrefix ?? "");
+        const documents = [...this.documents.values()]
+            .filter((document) => memoryScopeMatches(scope, document.scope))
+            .filter((document) => !prefix || document.path.startsWith(prefix));
+        return rankMemoryDocuments(documents, input);
+    }
+    async read(scope, input) {
+        const document = this.documents.get(memoryKey(scope, normalizeMemoryPath(input.path)));
+        if (!document || !memoryScopeMatches(scope, document.scope))
+            return undefined;
+        if (input.expectedRevision && input.expectedRevision !== document.revision) {
+            throw new Error(`Memory revision mismatch for ${document.path}.`);
+        }
+        const sliced = sliceMemoryDocument(document, input);
+        return sliced;
+    }
+    async write(scope, input) {
+        const path = normalizeMemoryPath(input.path);
+        const key = memoryKey(scope, path);
+        const current = this.documents.get(key);
+        if (input.expectedRevision && current?.revision !== input.expectedRevision) {
+            throw new Error(`Memory revision mismatch for ${path}.`);
+        }
+        const document = createMemoryDocument(scope, path, current, input);
+        this.documents.set(key, document);
+        await this.persist();
+        return document;
+    }
+    async persist() {
+        return;
+    }
+}
+export class FileMemoryStore extends InMemoryMemoryStore {
+    path;
+    constructor(path) {
+        super();
+        this.path = path;
+        this.load();
+    }
+    async persist() {
+        mkdirSync(dirname(this.path), { recursive: true });
+        writeAtomic(this.path, `${this.path}.tmp-${process.pid}`, JSON.stringify({ documents: [...this.documents.values()] }, null, 2));
+    }
+    load() {
+        if (!existsSync(this.path))
+            return;
+        const raw = readFileSync(this.path, "utf8");
+        let parsed;
+        try {
+            parsed = JSON.parse(raw);
+        }
+        catch {
+            const backupPath = `${this.path}.corrupt-${Date.now()}`;
+            writeFileSync(backupPath, raw);
+            process.emitWarning(`OpenEve memory store at ${this.path} was unreadable; backed up to ${backupPath} and starting fresh.`);
+            return;
+        }
+        for (const document of parsed.documents ?? []) {
+            this.documents.set(memoryKey(document.scope, document.path), document);
+        }
+    }
+}
+export class StateMemoryStore {
+    state;
+    embeddingProvider;
+    embeddingsEnabled;
+    constructor(state, embeddingProvider, embeddingsEnabled = false) {
+        this.state = state;
+        this.embeddingProvider = embeddingProvider;
+        this.embeddingsEnabled = embeddingsEnabled;
+    }
+    async list(scope, input = {}) {
+        const limit = input.limit === undefined ? 50 : input.limit;
+        return this.state.listMemoryDocuments(scope, { ...input, limit });
+    }
+    async search(scope, input) {
+        const wantsSemantic = input.mode === "semantic" || input.mode === "hybrid";
+        const lexicalMode = input.mode === "semantic" ? "keyword" : input.mode;
+        const lexicalInput = { ...input };
+        if (lexicalMode)
+            lexicalInput.mode = lexicalMode;
+        const lexical = input.mode === "semantic"
+            ? []
+            : this.state.searchMemoryDocuments
+                ? await this.state.searchMemoryDocuments(scope, lexicalInput)
+                : await this.portableSearch(scope, lexicalInput);
+        if (!wantsSemantic || !this.embeddingProvider || !this.embeddingsEnabled) {
+            return lexical.length > 0 ? lexical : input.mode === "semantic" ? await this.portableSearch(scope, lexicalInput) : lexical;
+        }
+        const queryEmbedding = await embedMemoryText(this.embeddingProvider, input.query, "query", {
+            searchMode: input.mode ?? "hybrid"
+        });
+        const semanticOptions = { model: queryEmbedding.model };
+        if (input.limit !== undefined)
+            semanticOptions.limit = input.limit;
+        const semantic = await this.state.searchMemoryEmbeddings(scope, input, queryEmbedding.embedding, semanticOptions);
+        if (input.mode === "semantic")
+            return semantic;
+        return mergeMemorySearchResults(semantic, lexical, input);
+    }
+    async portableSearch(scope, input) {
+        const listInput = {};
+        if (input.pathPrefix)
+            listInput.pathPrefix = input.pathPrefix;
+        const documents = await this.state.listMemoryDocuments(scope, listInput);
+        return rankMemoryDocuments(documents, input);
+    }
+    async read(scope, input) {
+        const document = await this.state.getMemoryDocument(scope, input.path);
+        if (!document)
+            return undefined;
+        if (input.expectedRevision && input.expectedRevision !== document.revision) {
+            throw new Error(`Memory revision mismatch for ${document.path}.`);
+        }
+        return sliceMemoryDocument(document, input);
+    }
+    async write(scope, input) {
+        const path = normalizeMemoryPath(input.path);
+        const current = await this.state.getMemoryDocument(scope, path);
+        if (input.expectedRevision && current?.revision !== input.expectedRevision) {
+            throw new Error(`Memory revision mismatch for ${path}.`);
+        }
+        const document = createMemoryDocument(scope, path, current, input);
+        const written = await this.state.upsertMemoryDocument(document);
+        if (this.embeddingsEnabled) {
+            await this.state.markMemoryEmbeddingsStale(scope, path, written.sha256);
+        }
+        return written;
+    }
+}
+export function normalizeSandboxSyncJobRecord(job) {
+    const createdAt = job.createdAt ?? timestamp();
+    const record = {
+        ...job,
+        status: job.status ?? "pending",
+        manifest: job.manifest ?? {},
+        attemptCount: typeof job.attemptCount === "number" ? job.attemptCount : 0,
+        maxAttempts: typeof job.maxAttempts === "number" ? job.maxAttempts : 5,
+        nextAttemptAt: job.nextAttemptAt ?? createdAt,
+        metadata: job.metadata ?? {},
+        createdAt,
+        updatedAt: job.updatedAt ?? createdAt
+    };
+    return record;
+}
+export function memoryEmbeddingDocumentText(document, maxTokens) {
+    const parts = [
+        document.path,
+        document.title ?? "",
+        document.summary ?? "",
+        document.tags.join(" "),
+        memoryBodyText(document)
+    ].filter(Boolean);
+    const text = parts.join("\n");
+    const limit = positiveLimit(maxTokens, 2_000);
+    return text.slice(0, limit * 4);
+}
+export function sliceMemoryDocument(document, input) {
+    let body = memoryBodyText(document);
+    if (input.range) {
+        const lines = body.split(/\r?\n/u);
+        const start = Math.max(0, Math.floor(input.range.startLine) - 1);
+        const end = Math.max(start, Math.floor(input.range.endLine));
+        body = lines.slice(start, end).join("\n");
+    }
+    const maxTokens = positiveLimit(input.maxTokens, 0);
+    if (maxTokens > 0) {
+        const maxChars = maxTokens * 4;
+        body = body.length > maxChars ? `${body.slice(0, Math.max(0, maxChars - 3))}...` : body;
+    }
+    return {
+        ...document,
+        body,
+        tokenEstimate: estimateTokens(body)
+    };
+}
+export function nextMemoryBody(previous, content, mode) {
+    if (mode === "replace")
+        return content;
+    if (mode === "append") {
+        if (!previous)
+            return content;
+        return `${previous.replace(/\s*$/u, "")}\n${content}`;
+    }
+    if (mode === "patch")
+        return content;
+    throw new Error(`Unsupported memory write mode: ${mode}`);
+}
+export function createMemoryDocument(scope, path, current, input) {
+    const previous = current ? memoryBodyText(current) : "";
+    const nextBody = nextMemoryBody(previous, input.content, input.mode);
+    const now = timestamp();
+    const metadata = input.metadata ?? {};
+    const bodyHash = createHash("sha256").update(nextBody).digest("hex");
+    const document = {
+        scope,
+        path,
+        body: nextBody,
+        contentType: "text/markdown",
+        tags: metadata.tags ?? current?.tags ?? [],
+        tokenEstimate: estimateTokens(nextBody),
+        sha256: bodyHash,
+        revision: `${bodyHash.slice(0, 16)}:${Date.parse(now) || Date.now()}`,
+        createdAt: current?.createdAt ?? now,
+        updatedAt: now
+    };
+    const title = metadata.title ?? current?.title;
+    const summary = metadata.summary ?? current?.summary;
+    const confidence = metadata.confidence ?? current?.confidence;
+    const sourceRefs = metadata.sourceRefs ?? current?.sourceRefs;
+    if (title)
+        document.title = title;
+    if (summary)
+        document.summary = summary;
+    if (confidence)
+        document.confidence = confidence;
+    if (sourceRefs)
+        document.sourceRefs = sourceRefs;
+    return document;
+}
+export function rankMemoryDocuments(documents, input) {
+    const query = stringValue(input.query).toLowerCase();
+    const normalizedQuery = normalizeMemoryPath(query).toLowerCase();
+    const limit = positiveLimit(input.limit, 8);
+    const ranked = documents
+        .map((document) => {
+        const body = memoryBodyText(document);
+        const tagText = document.tags.join(" ");
+        const haystack = `${document.path}\n${document.title ?? ""}\n${document.summary ?? ""}\n${tagText}\n${body}`.toLowerCase();
+        const pathExact = Boolean(query && (document.path.toLowerCase() === query || document.path.toLowerCase() === normalizedQuery));
+        const phraseMatch = Boolean(query && haystack.includes(query));
+        const terms = query.split(/\s+/u).filter(Boolean);
+        const tagMatch = terms.some((term) => document.tags.some((tag) => tag.toLowerCase().includes(term)));
+        const termMatches = terms.filter((term) => haystack.includes(term)).length;
+        const score = (pathExact ? 1000 : 0) + (phraseMatch ? 100 : 0) + (tagMatch ? 20 : 0) + termMatches;
+        return { document, body, score, pathExact, phraseMatch, tagMatch };
+    })
+        .filter((entry) => input.mode === "exact" && query ? entry.pathExact : query ? entry.score > 0 : true)
+        .sort((a, b) => b.score - a.score || b.document.updatedAt.localeCompare(a.document.updatedAt))
+        .slice(0, limit);
+    return ranked.map(({ document, body, pathExact, phraseMatch, tagMatch }) => ({
+        path: document.path,
+        ...(document.title ? { title: document.title } : {}),
+        ...(document.summary ? { summary: document.summary } : {}),
+        snippet: memorySnippet(body, query),
+        revision: document.revision,
+        tags: document.tags,
+        updatedAt: document.updatedAt,
+        rankReason: memoryRankReason({ pathExact, phraseMatch, tagMatch, keywordMatch: Boolean(query), recencyBoost: true })
+    }));
+}
+export function memoryRankReason(signals) {
+    const reasons = [];
+    if (signals.pathExact)
+        reasons.push("exact path match");
+    if (signals.phraseMatch && !signals.pathExact)
+        reasons.push("phrase match");
+    if (signals.tagMatch)
+        reasons.push("tag match");
+    if (typeof signals.fullTextRank === "number" && signals.fullTextRank > 0)
+        reasons.push(`full-text rank ${signals.fullTextRank.toFixed(3)}`);
+    if (signals.keywordMatch && reasons.length === 0)
+        reasons.push("keyword match");
+    if (signals.recencyBoost)
+        reasons.push("recency boost");
+    return reasons.join("; ") || "recency boost";
+}
+export async function embedMemoryText(provider, text, purpose, metadata = {}) {
+    const bounded = text.slice(0, positiveLimit(provider.maxInputTokens, 2_000) * 4);
+    const output = await provider.embed({ text: bounded, purpose, model: provider.model, metadata });
+    const embedding = output.embedding.filter((value) => Number.isFinite(value));
+    return {
+        embedding,
+        model: output.model ?? provider.model,
+        dimensions: output.dimensions ?? embedding.length
+    };
+}
+export function mergeMemorySearchResults(semantic, lexical, input) {
+    const limit = positiveLimit(input.limit, 8);
+    const byPath = new Map();
+    for (const result of semantic) {
+        byPath.set(result.path, result);
+    }
+    for (const result of lexical) {
+        const existing = byPath.get(result.path);
+        byPath.set(result.path, existing
+            ? {
+                ...existing,
+                snippet: existing.snippet || result.snippet,
+                rankReason: `${existing.rankReason}; ${result.rankReason}`
+            }
+            : result);
+    }
+    return [...byPath.values()].slice(0, limit);
+}
+export function estimateTokens(text) {
+    return Math.ceil(text.length / 4);
+}
+export function deliveryRetryDelayMs(attempt, minDelayMs, maxDelayMs) {
+    const cap = Math.max(minDelayMs, maxDelayMs);
+    const exponential = minDelayMs * 2 ** Math.max(0, attempt - 1);
+    return Math.min(cap, exponential);
+}
+export function sleepMs(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+export function memoryDocumentSummary(document) {
+    return {
+        path: document.path,
+        title: document.title ?? null,
+        summary: document.summary ?? null,
+        tags: document.tags,
+        revision: document.revision,
+        tokenEstimate: document.tokenEstimate,
+        updatedAt: document.updatedAt
+    };
+}
+export function memoryDocumentForModel(document) {
+    return {
+        ...memoryDocumentSummary(document),
+        contentType: document.contentType,
+        body: memoryBodyText(document)
+    };
+}
+//# sourceMappingURL=storage.js.map