@draht/agent-core 2026.7.30 → 2026.10.4-2

package/dist/harness/session/session.js

@@ -1,261 +1,361 @@
-import { createBranchSummaryMessage, createCompactionSummaryMessage, createCustomMessage } from "../messages.js";
-import { SessionError } from "../types.js";
-function deriveSessionContextState(pathEntries) {
-    let thinkingLevel = "off";
-    let model = null;
-    let activeToolNames = null;
-    for (const entry of pathEntries) {
-        if (entry.type === "thinking_level_change") {
-            thinkingLevel = entry.thinkingLevel;
-        }
-        else if (entry.type === "model_change") {
-            model = { provider: entry.provider, modelId: entry.modelId };
-        }
-        else if (entry.type === "message" && entry.message.role === "assistant") {
-            model = { provider: entry.message.provider, modelId: entry.message.model };
-        }
-        else if (entry.type === "active_tools_change") {
-            activeToolNames = [...entry.activeToolNames];
-        }
+import { uuidv7 } from "@draht/ai/utils/uuid";
+import { insertEntry } from "./commit.js";
+import { MutationLine } from "./mutation-line.js";
+import { appendList as appendListWrite, branchTip, deleteList as deleteListWrite, deleteValue as deleteValueWrite, entryLabel, sessionName, setValue as setValueWrite, } from "./values.js";
+/** Durable session state is internally inconsistent and cannot be safely advanced. */
+export class SessionInvariantError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "SessionInvariantError";
     }
-    return { thinkingLevel, model, activeToolNames };
 }
-export function defaultContextEntryTransform(pathEntries) {
-    let compaction = null;
-    for (const entry of pathEntries) {
-        if (entry.type === "compaction") {
-            compaction = entry;
-        }
+/** A requested Branch name is invalid. */
+export class SessionInvalidBranchError extends Error {
+    branch;
+    reason;
+    constructor(branch, reason) {
+        super(`Invalid branch ${JSON.stringify(branch)}: ${reason}`);
+        this.name = "SessionInvalidBranchError";
+        this.branch = branch;
+        this.reason = reason;
     }
-    if (!compaction) {
-        return [...pathEntries];
-    }
-    const entries = [compaction];
-    const compactionIdx = pathEntries.findIndex((entry) => entry.type === "compaction" && entry.id === compaction.id);
-    if (compaction.retainedTail) {
-        for (let i = compactionIdx + 1; i < pathEntries.length; i++) {
-            entries.push(pathEntries[i]);
-        }
-        return entries;
-    }
-    if (compaction.firstKeptEntryId) {
-        let foundFirstKept = false;
-        for (let i = 0; i < compactionIdx; i++) {
-            const entry = pathEntries[i];
-            if (entry.id === compaction.firstKeptEntryId)
-                foundFirstKept = true;
-            if (foundFirstKept)
-                entries.push(entry);
-        }
-    }
-    for (let i = compactionIdx + 1; i < pathEntries.length; i++) {
-        entries.push(pathEntries[i]);
+}
+/** A requested branch already exists. */
+export class SessionBranchExistsError extends Error {
+    branch;
+    constructor(branch) {
+        super(`Branch already exists: ${branch}`);
+        this.name = "SessionBranchExistsError";
+        this.branch = branch;
     }
-    return entries;
 }
-export function buildContextEntries(pathEntries, options = {}) {
-    let entries = defaultContextEntryTransform(pathEntries);
-    for (const transform of options.entryTransforms ?? []) {
-        entries = [...transform(entries)];
+/** A pending assistant message cannot be persisted as a session entry. */
+export class SessionPendingAssistantMessageError extends Error {
+    constructor() {
+        super("Cannot persist a pending assistant message");
+        this.name = "SessionPendingAssistantMessageError";
     }
-    return entries;
 }
-export function sessionEntryToContextMessages(entry, index, entries, options = {}) {
-    if (entry.type === "message") {
-        return [entry.message];
+/** A requested session entry target does not exist. */
+export class SessionUnknownTargetError extends Error {
+    targetId;
+    constructor(targetId) {
+        super(`Unknown target: ${targetId}`);
+        this.name = "SessionUnknownTargetError";
+        this.targetId = targetId;
     }
-    if (entry.type === "custom_message") {
-        return [
-            createCustomMessage(entry.customType, entry.content, entry.display, entry.details, entry.timestamp),
-        ];
+}
+class StorageBackedSessionMutation {
+    storage;
+    release;
+    active = true;
+    commitResult;
+    endPromise;
+    constructor(storage, release) {
+        this.storage = storage;
+        this.release = release;
+    }
+    commit(writes, context) {
+        this.assertActive();
+        if (this.commitResult !== undefined)
+            return Promise.reject(new Error("SessionMutator commit already attempted"));
+        try {
+            for (const write of writes) {
+                if (write.kind === "entry" &&
+                    write.entry.type === "message" &&
+                    write.entry.message.role === "assistant" &&
+                    write.entry.message.stopReason === "pending") {
+                    throw new SessionPendingAssistantMessageError();
+                }
+            }
+            this.commitResult = this.storage.commit(writes, context);
+        }
+        catch (error) {
+            this.commitResult = Promise.reject(error);
+        }
+        return this.commitResult;
     }
-    if (entry.type === "compaction") {
-        return [
-            createCompactionSummaryMessage(entry.summary, entry.tokensBefore, entry.timestamp),
-            ...(entry.retainedTail ?? []),
-        ];
+    end(_context) {
+        if (this.endPromise !== undefined)
+            return this.endPromise;
+        this.active = false;
+        this.endPromise = this.settle().finally(this.release);
+        return this.endPromise;
     }
-    if (entry.type === "branch_summary" && entry.summary) {
-        return [createBranchSummaryMessage(entry.summary, entry.fromId, entry.timestamp)];
+    getEntries(ids, context) {
+        this.assertActive();
+        return this.storage.getEntries(ids, context);
     }
-    if (entry.type === "custom") {
-        return [...(options.entryProjectors?.[entry.customType]?.(entry, index, entries) ?? [])];
+    getStats(context) {
+        this.assertActive();
+        return this.storage.getStats(context);
     }
-    return [];
-}
-export function buildSessionContext(pathEntries, options = {}) {
-    const state = deriveSessionContextState(pathEntries);
-    const contextEntries = buildContextEntries(pathEntries, options);
-    const messages = contextEntries.flatMap((entry, index) => sessionEntryToContextMessages(entry, index, contextEntries, options));
-    return { ...state, messages };
-}
-export class Session {
-    constructor(storage, contextBuildOptions = {}) {
-        this.storage = storage;
-        this.contextBuildOptions = contextBuildOptions;
+    getValue(address, context) {
+        this.assertActive();
+        return this.storage.getValue(address, context);
     }
-    getMetadata() {
-        return this.storage.getMetadata();
+    scanValues(prefix, context) {
+        this.assertActive();
+        return this.storage.scanValues(prefix, context);
     }
-    getStorage() {
-        return this.storage;
+    readList(address, options, context) {
+        this.assertActive();
+        return this.storage.readList(address, options, context);
     }
-    getLeafId() {
-        return this.storage.getLeafId();
+    scanBranch(query, context) {
+        this.assertActive();
+        return this.storage.scanBranch(query, context);
     }
-    getEntry(id) {
-        return this.storage.getEntry(id);
+    settle() {
+        return (this.commitResult?.then(() => undefined, () => undefined) ?? Promise.resolve());
     }
-    getEntries(options) {
-        return this.storage.getEntries(options);
+    assertActive() {
+        if (!this.active)
+            throw new Error("SessionMutator cannot be used outside its mutation callback");
     }
-    async getBranch(fromId) {
-        const leafId = fromId ?? (await this.storage.getLeafId());
-        return this.storage.getPathToRootOrCompaction(leafId);
+}
+class StorageBackedBranch {
+    name;
+    session;
+    constructor(name, session) {
+        this.name = name;
+        this.session = session;
     }
-    async buildContextEntries(options = {}) {
-        return buildContextEntries(await this.getBranch(), this.mergeContextBuildOptions(options));
+    getTipId(context) {
+        return this.session.getBranchTip(this.name, context);
     }
-    async buildContext(options = {}) {
-        return buildSessionContext(await this.getBranch(), this.mergeContextBuildOptions(options));
+    async findEntries(query, context) {
+        query ??= {};
+        const start = query.start ?? (await this.getTipId(context));
+        if (start === null)
+            return [];
+        return this.session.scanBranch({ ...query, start, order: query.order ?? "newestFirst" }, context);
     }
-    mergeContextBuildOptions(options) {
-        return {
-            entryTransforms: [...(this.contextBuildOptions.entryTransforms ?? []), ...(options.entryTransforms ?? [])],
-            entryProjectors: {
-                ...(this.contextBuildOptions.entryProjectors ?? {}),
-                ...(options.entryProjectors ?? {}),
-            },
-        };
+    async findEntry(query, context) {
+        query ??= {};
+        return (await this.findEntries({ ...query, limit: query.limit === undefined ? 1 : Math.min(query.limit, 1) }, context))[0];
     }
-    getLabel(id) {
-        return this.storage.getLabel(id);
+    appendMessage(message, context) {
+        return this.session.appendToBranch(this.name, { type: "message", message }, context);
     }
-    getSessionStats() {
-        return this.storage.getSessionStats();
+    appendCustomEntry(customType, data, context) {
+        return this.session.appendToBranch(this.name, { type: "custom", customType, ...(data === undefined ? {} : { data }) }, context);
     }
-    async getSessionName() {
-        return this.storage.getSessionName();
+}
+/** Package-internal typed boundary shared by concrete session repositories. */
+export class StorageBackedSession {
+    metadata;
+    idGenerator;
+    storage;
+    mutationLine;
+    onClose;
+    branches = new Map();
+    closedError = new Error("Session is closed");
+    state = "open";
+    closePromise;
+    constructor(metadata, storage, options = {}) {
+        this.metadata = metadata;
+        this.idGenerator = options.idGenerator ?? { next: uuidv7 };
+        this.storage = storage;
+        this.mutationLine = options.mutationLine ?? new MutationLine();
+        this.onClose = options.onClose;
+    }
+    async beginMutation(_context) {
+        this.assertOpen();
+        let grant;
+        let rejectGrant;
+        const granted = new Promise((resolve, reject) => {
+            grant = resolve;
+            rejectGrant = reject;
+        });
+        let release;
+        const finished = new Promise((resolve) => {
+            release = resolve;
+        });
+        const line = this.mutationLine.run(async () => {
+            grant(new StorageBackedSessionMutation(this.storage, release));
+            await finished;
+        });
+        void line.catch(rejectGrant);
+        return granted;
     }
-    async appendTypedEntry(entry) {
-        await this.storage.appendEntry(entry);
-        return entry.id;
+    async mutate(mutation, context) {
+        const mutator = await this.beginMutation(context);
+        try {
+            return await mutation(mutator, context);
+        }
+        finally {
+            await mutator.end(context);
+        }
     }
-    async appendMessage(message) {
-        return this.appendTypedEntry({
-            type: "message",
-            id: await this.storage.createEntryId(),
-            parentId: await this.storage.getLeafId(),
-            timestamp: new Date().toISOString(),
-            message,
-        });
+    async getEntries(ids, context) {
+        this.assertOpen();
+        return this.storage.getEntries(ids, context);
     }
-    async appendThinkingLevelChange(thinkingLevel) {
-        return this.appendTypedEntry({
-            type: "thinking_level_change",
-            id: await this.storage.createEntryId(),
-            parentId: await this.storage.getLeafId(),
-            timestamp: new Date().toISOString(),
-            thinkingLevel,
-        });
+    async getEntry(id, context) {
+        return (await this.getEntries([id], context)).get(id);
     }
-    async appendModelChange(provider, modelId) {
-        return this.appendTypedEntry({
-            type: "model_change",
-            id: await this.storage.createEntryId(),
-            parentId: await this.storage.getLeafId(),
-            timestamp: new Date().toISOString(),
-            provider,
-            modelId,
-        });
+    async getValue(address, context) {
+        this.assertOpen();
+        return this.storage.getValue(address, context);
     }
-    async appendActiveToolsChange(activeToolNames) {
-        return this.appendTypedEntry({
-            type: "active_tools_change",
-            id: await this.storage.createEntryId(),
-            parentId: await this.storage.getLeafId(),
-            timestamp: new Date().toISOString(),
-            activeToolNames: [...activeToolNames],
-        });
+    async scanValues(prefix, context) {
+        this.assertOpen();
+        return this.storage.scanValues(prefix, context);
     }
-    async appendCompaction(summary, firstKeptEntryId, tokensBefore, details, fromHook, usage, retainedTail) {
-        return this.appendTypedEntry({
-            type: "compaction",
-            id: await this.storage.createEntryId(),
-            parentId: await this.storage.getLeafId(),
-            timestamp: new Date().toISOString(),
-            summary,
-            firstKeptEntryId,
-            tokensBefore,
-            retainedTail,
-            details,
-            usage,
-            fromHook,
-        });
+    async readList(address, options, context) {
+        this.assertOpen();
+        return this.storage.readList(address, options, context);
     }
-    async appendCustomEntry(customType, data) {
-        return this.appendTypedEntry({
-            type: "custom",
-            id: await this.storage.createEntryId(),
-            parentId: await this.storage.getLeafId(),
-            timestamp: new Date().toISOString(),
-            customType,
-            data,
-        });
+    async scanBranch(query, context) {
+        this.assertOpen();
+        return this.storage.scanBranch(query, context);
     }
-    async appendCustomMessageEntry(customType, content, display, details) {
-        return this.appendTypedEntry({
-            type: "custom_message",
-            id: await this.storage.createEntryId(),
-            parentId: await this.storage.getLeafId(),
-            timestamp: new Date().toISOString(),
-            customType,
-            content,
-            display,
-            details,
-        });
+    async getStats(context) {
+        this.assertOpen();
+        return this.storage.getStats(context);
     }
-    async appendLabel(targetId, label) {
-        if (!(await this.storage.getEntry(targetId))) {
-            throw new SessionError("not_found", `Entry ${targetId} not found`);
-        }
-        return this.appendTypedEntry({
-            type: "label",
-            id: await this.storage.createEntryId(),
-            parentId: await this.storage.getLeafId(),
-            timestamp: new Date().toISOString(),
-            targetId,
-            label,
-        });
+    async getName(context) {
+        return (await this.getValue(sessionName, context))?.value;
     }
-    async appendSessionName(name) {
-        const sanitizedName = name.replace(/[\r\n]+/g, " ").trim();
-        return this.appendTypedEntry({
-            type: "session_info",
-            id: await this.storage.createEntryId(),
-            parentId: await this.storage.getLeafId(),
-            timestamp: new Date().toISOString(),
-            name: sanitizedName,
-        });
+    async getLabel(targetId, context) {
+        return (await this.getValue(entryLabel(targetId), context))?.value;
     }
-    async moveTo(entryId, summary) {
-        if (entryId !== null && !(await this.storage.getEntry(entryId))) {
-            throw new SessionError("not_found", `Entry ${entryId} not found`);
+    async findEntries(query, context) {
+        query ??= {};
+        this.assertOpen();
+        const order = query.order ?? "desc";
+        if (query.cursor !== undefined) {
+            if (order === "asc" && query.cursor.seq === Number.MAX_SAFE_INTEGER)
+                return [];
+            if (order === "desc" && query.cursor.seq <= 1)
+                return [];
         }
-        await this.storage.setLeafId(entryId);
-        if (!summary)
+        return this.storage.scanEntries({
+            type: query.type,
+            customType: query.customType,
+            order,
+            limit: query.limit,
+            ...(query.cursor === undefined
+                ? {}
+                : order === "asc"
+                    ? { fromSeq: query.cursor.seq + 1 }
+                    : { toSeq: query.cursor.seq - 1 }),
+        }, context);
+    }
+    async findEntry(query, context) {
+        query ??= {};
+        return (await this.findEntries({ ...query, limit: query.limit === undefined ? 1 : Math.min(query.limit, 1) }, context))[0];
+    }
+    async branch(name, context) {
+        this.assertValidBranchName(name);
+        if ((await this.getValue(branchTip(name), context)) === undefined)
             return undefined;
-        return this.appendTypedEntry({
-            type: "branch_summary",
-            id: await this.storage.createEntryId(),
-            parentId: entryId,
-            timestamp: new Date().toISOString(),
-            fromId: entryId ?? "root",
-            summary: summary.summary,
-            details: summary.details,
-            usage: summary.usage,
-            fromHook: summary.fromHook,
+        return this.getOrCreateBranchObject(name);
+    }
+    async createBranch(name, at, context) {
+        this.assertOpen();
+        this.assertValidBranchName(name);
+        await this.mutate(async (mutator) => {
+            if ((await mutator.getValue(branchTip(name), context)) !== undefined) {
+                throw new SessionBranchExistsError(name);
+            }
+            if (at !== null && !(await mutator.getEntries([at], context)).has(at)) {
+                throw new SessionUnknownTargetError(at);
+            }
+            await mutator.commit([setValueWrite(branchTip(name), at)], context);
+        }, context);
+        return this.getOrCreateBranchObject(name);
+    }
+    setValue(address, next, context) {
+        return this.mutate(async (mutator) => {
+            await mutator.commit([setValueWrite(address, next)], context);
+        }, context);
+    }
+    deleteValue(address, context) {
+        return this.mutate(async (mutator) => {
+            await mutator.commit([deleteValueWrite(address)], context);
+        }, context);
+    }
+    appendList(address, element, context) {
+        return this.mutate(async (mutator) => {
+            await mutator.commit([appendListWrite(address, element)], context);
+        }, context);
+    }
+    deleteList(address, context) {
+        return this.mutate(async (mutator) => {
+            await mutator.commit([deleteListWrite(address)], context);
+        }, context);
+    }
+    setName(name, context) {
+        return name === undefined ? this.deleteValue(sessionName, context) : this.setValue(sessionName, name, context);
+    }
+    setLabel(targetId, label, context) {
+        const address = entryLabel(targetId);
+        return label === undefined ? this.deleteValue(address, context) : this.setValue(address, label, context);
+    }
+    close(context) {
+        if (this.closePromise !== undefined)
+            return this.closePromise;
+        this.state = "closing";
+        this.closePromise = this.mutationLine
+            .seal(this.closedError)
+            .then(() => this.storage.close(context))
+            .finally(() => {
+            this.state = "closed";
+            this.onClose?.();
         });
+        return this.closePromise;
+    }
+    async getBranchTip(name, context) {
+        const stored = await this.getValue(branchTip(name), context);
+        if (stored === undefined)
+            throw new SessionInvariantError(`Unknown branch: ${name}`);
+        return stored.value;
+    }
+    async appendToBranch(name, entry, context) {
+        this.assertOpen();
+        if (entry.type === "message" && entry.message.role === "assistant" && entry.message.stopReason === "pending") {
+            throw new SessionPendingAssistantMessageError();
+        }
+        const id = this.idGenerator.next();
+        await this.mutate(async (mutator) => {
+            const tip = await mutator.getValue(branchTip(name), context);
+            if (tip === undefined)
+                throw new SessionInvariantError(`Unknown branch: ${name}`);
+            await mutator.commit([
+                insertEntry(entry.type === "message"
+                    ? { id, parentId: tip.value, type: "message", message: entry.message }
+                    : {
+                        id,
+                        parentId: tip.value,
+                        type: "custom",
+                        customType: entry.customType,
+                        ...(entry.data === undefined ? {} : { data: entry.data }),
+                    }),
+                setValueWrite(branchTip(name), id),
+            ], context);
+        }, context);
+        return id;
+    }
+    getOrCreateBranchObject(name) {
+        let branch = this.branches.get(name);
+        if (branch === undefined) {
+            branch = new StorageBackedBranch(name, this);
+            this.branches.set(name, branch);
+        }
+        return branch;
+    }
+    assertValidBranchName(name) {
+        if (name.length === 0)
+            throw new SessionInvalidBranchError(name, "branch name must not be empty");
+        if (name.includes("\u0000")) {
+            throw new SessionInvalidBranchError(name, "branch name must not contain \\u0000");
+        }
+    }
+    assertOpen() {
+        if (this.state !== "open")
+            throw this.closedError;
     }
 }
 //# sourceMappingURL=session.js.map