sakura-agent 0.1.0 → 0.1.1

package/dist/packages/plugins/toolset/src/codemode.js

@@ -1,5 +1,7 @@
 import { getQuickJS } from "quickjs-emscripten";
-const DESCRIPTION = "Runs a short JavaScript program in a sandbox (no files, no network, no timers) and returns what it prints and returns. " +
+/** The name of the tool that runs a script. Whoever needs to refer to it takes it from here. */
+export const CODEMODE_TOOL = "run_code";
+const DESCRIPTION = "Runs a short JavaScript program in an isolated runtime (no files, no network, no timers) and returns what it prints and returns. " +
     "Inside the program, `tools.<name>(args)` calls a tool and returns a promise of its text; use `await`. `console.log` output is returned. " +
     "Use it to combine several tool calls or to process their results without sending everything through the conversation. Available tools: ";
 const PRELUDE = `
@@ -10,7 +12,7 @@ globalThis.tools = new Proxy({}, { get: (_t, name) => async (args) => {
 } });
 globalThis.console = { log: (...parts) => __print(parts.map((p) => (typeof p === "string" ? p : JSON.stringify(p))).join(" ")) };
 `;
-/** Deeper than this, the host's own stack overflows before the sandbox notices, which aborts the whole WebAssembly module; 256 KB still allows recursion about 1500 deep. */
+/** Deeper than this, the host's own stack overflows before the runtime notices, which aborts the whole WebAssembly module; 256 KB still allows recursion about 1500 deep. */
 const STACK_BYTES = 256 * 1024;
 const text = (value, isError = false) => ({ content: [{ type: "text", text: value }], ...(isError ? { isError } : {}) });
 const textOfContent = (content) => content.map((part) => (part.type === "text" ? part.text : `[${part.type}]`)).join("\n");
@@ -23,11 +25,14 @@ function cut(value, limit) {
 /**
  * Lets the model write one JavaScript program that calls tools, instead of one call per request. The program runs in QuickJS
  * (WebAssembly), which has no access to the machine: only the tools in the catalog, and only those whose effect is allowed.
- * Calls made from the script do not pass through the hooks of the loop. Two things stand in for them: only read-only tools are allowed by default,
- * and `authorize` (for example the review plugin's) is asked before each call.
+ * Calls made from the script do not pass through the hooks of the loop, so `authorize` (for example the review plugin's) is asked
+ * before each call. With no `authorize`, every call runs, as a direct call would with no review installed.
+ *
+ * The runtime only keeps the script itself away from the machine. The tools it calls (a shell command, a file write, an MCP tool) run outside the
+ * runtime with their full power, so a call from a script is exactly as risky as the same call made directly, and needs the same review.
  */
 export function codemodePlugin(options) {
-    const allowed = new Set(options.allowEffects ?? ["read"]);
+    const allowed = new Set(options.allowEffects ?? ["read", "write", "exec", "network", "irreversible"]);
     const byName = new Map(options.catalog.map((tool) => [tool.name, tool]));
     const timeoutMs = options.timeoutMs ?? 10_000;
     const memoryBytes = options.memoryBytes ?? 64 * 1024 * 1024;
@@ -42,7 +47,7 @@ export function codemodePlugin(options) {
         try {
             const args = JSON.parse(rawArgs);
             if (options.authorize) {
-                const decision = await options.authorize({ id: `${context.callId}/${++calls}`, name, args }, { log: context.log, signal: context.signal, tool: (wanted) => byName.get(wanted) });
+                const decision = await options.authorize({ id: `${context.callId}/${++calls}`, name, args }, { log: context.log, signal: context.signal, tool: (wanted) => byName.get(wanted), ...(context.env?.cwd !== undefined ? { cwd: context.env.cwd } : {}) });
                 if (decision.kind === "deny")
                     return JSON.stringify({ error: decision.reason });
             }
@@ -55,7 +60,7 @@ export function codemodePlugin(options) {
         }
     }
     const runCode = {
-        name: "run_code",
+        name: CODEMODE_TOOL,
         description: DESCRIPTION + options.catalog.map((tool) => tool.name).join(", "),
         parameters: { type: "object", properties: { code: { type: "string", description: "The body of an async function; use `return` for the result" } }, required: ["code"] },
         effect: "exec",
@@ -68,13 +73,45 @@ export function codemodePlugin(options) {
             const runtime = QuickJS.newRuntime();
             runtime.setMemoryLimit(memoryBytes);
             runtime.setMaxStackSize(STACK_BYTES);
-            const deadline = Date.now() + timeoutMs;
-            runtime.setInterruptHandler(() => Date.now() > deadline || context.signal.aborted);
+            // The script's own time is the time spent inside the runtime plus the time spent waiting while no tool call is under way.
+            // Waiting for a tool call is not counted, but a loop that runs while a call is under way is (it is counted as it runs).
+            const startedAt = Date.now();
+            let insideMs = 0;
+            let idleMs = 0;
+            let sliceStart = 0;
+            const used = () => insideMs + idleMs + (sliceStart > 0 ? Date.now() - sliceStart : 0);
+            const inRuntime = (work) => {
+                if (sliceStart > 0)
+                    return work();
+                sliceStart = Date.now();
+                try {
+                    return work();
+                }
+                finally {
+                    insideMs += Date.now() - sliceStart;
+                    sliceStart = 0;
+                }
+            };
+            const overTotal = () => options.totalTimeoutMs !== undefined && Date.now() - startedAt > options.totalTimeoutMs;
+            runtime.setInterruptHandler(() => used() > timeoutMs || overTotal() || context.signal.aborted);
             const vm = runtime.newContext();
             const printed = [];
-            const pending = [];
+            const unsettled = new Set(); // the calls that have not come back yet; the wait below must not include the ones that have, or it would not wait
             const handles = [];
             const deferreds = [];
+            // The calls that have not returned. Each has its own signal, joined to the run's: cancelling the run stops them all, and when the script
+            // ends the ones still under way are stopped. A call that has returned (a background command, say) is left to the run.
+            const underway = new Set();
+            const failure = (message) => text(printed.length > 0 ? cut(`${printed.join("\n")}\n${message}`, maxOutput) : message, true);
+            const late = () => {
+                if (context.signal.aborted)
+                    return "The script was cancelled."; // the calls it was waiting for were stopped with the run, so the script may report their errors instead
+                if (used() > timeoutMs)
+                    return `The script took longer than ${seconds(timeoutMs)} seconds and was stopped.`;
+                if (overTotal())
+                    return `The script took longer than ${seconds(options.totalTimeoutMs ?? 0)} seconds in total and was stopped.`;
+                return undefined;
+            };
             try {
                 const print = vm.newFunction("__print", (line) => {
                     printed.push(vm.getString(line));
@@ -86,54 +123,71 @@ export function codemodePlugin(options) {
                     deferreds.push(promise);
                     const name = vm.getString(nameHandle);
                     const rawArgs = vm.getString(argsHandle);
-                    const work = callTool(name, rawArgs, context).then((reply) => {
+                    const controller = new AbortController();
+                    const stop = () => controller.abort();
+                    if (context.signal.aborted)
+                        stop();
+                    else
+                        context.signal.addEventListener("abort", stop, { once: true }); // stays joined after the call returns, so a background command it started is still stopped with the run
+                    underway.add(controller);
+                    const work = callTool(name, rawArgs, { ...context, signal: controller.signal })
+                        .then((reply) => {
                         if (!vm.alive)
                             return;
                         const value = vm.newString(reply);
                         promise.resolve(value);
                         value.dispose();
+                    })
+                        .catch(() => undefined)
+                        .finally(() => {
+                        underway.delete(controller);
+                        unsettled.delete(work);
                     });
-                    pending.push(work);
+                    unsettled.add(work);
                     void promise.settled
                         .then(() => {
                         if (runtime.alive)
-                            runtime.executePendingJobs(); // the script may be over and the sandbox gone by now
+                            inRuntime(() => runtime.executePendingJobs()); // the script may be over and the runtime gone by now
                     })
                         .catch(() => undefined);
                     return promise.handle;
                 });
                 vm.setProp(vm.global, "__callTool", call);
                 call.dispose();
-                const prelude = vm.evalCode(PRELUDE);
+                const prelude = inRuntime(() => vm.evalCode(PRELUDE));
                 if (prelude.error) {
                     prelude.error.dispose();
-                    return text("The sandbox could not start.", true);
+                    return text("The script runtime could not start.", true);
                 }
                 prelude.value.dispose();
-                const evaluated = vm.evalCode(`(async () => {\n${code}\n})()`);
+                const evaluated = inRuntime(() => vm.evalCode(`(async () => {\n${code}\n})()`));
                 if (evaluated.error) {
                     const message = vm.dump(evaluated.error);
                     evaluated.error.dispose();
-                    return text(`Script error: ${formatError(message)}`, true);
+                    return failure(late() ?? `Script error: ${formatError(message)}`);
                 }
                 handles.push(evaluated.value);
-                runtime.executePendingJobs();
+                inRuntime(() => runtime.executePendingJobs());
                 // the script is done when its promise settles; tool calls it started finish in between
                 let state = vm.getPromiseState(evaluated.value);
+                let tick = Date.now();
                 while (state.type === "pending") {
-                    if (Date.now() > deadline)
-                        return text(`The script took longer than ${Math.round(timeoutMs / 1000)} seconds and was stopped.`, true);
-                    if (context.signal.aborted)
-                        return text("The script was cancelled.", true);
-                    await Promise.race([Promise.allSettled(pending), new Promise((resolve) => setTimeout(resolve, 20))]);
-                    runtime.executePendingJobs();
+                    const now = Date.now();
+                    if (underway.size === 0)
+                        idleMs += now - tick;
+                    tick = now;
+                    const over = late();
+                    if (over)
+                        return failure(over);
+                    await Promise.race([...unsettled, new Promise((resolve) => setTimeout(resolve, 20))]);
+                    inRuntime(() => runtime.executePendingJobs());
                     state = vm.getPromiseState(evaluated.value);
                 }
                 const output = printed.length > 0 ? `${printed.join("\n")}\n` : "";
                 if (state.type === "rejected") {
                     const message = vm.dump(state.error);
                     state.error.dispose();
-                    return text(cut(`${output}Script error: ${formatError(message)}`, maxOutput), true);
+                    return failure(late() ?? `Script error: ${formatError(message)}`);
                 }
                 const value = vm.dump(state.value);
                 state.value.dispose();
@@ -142,9 +196,11 @@ export function codemodePlugin(options) {
                 return text(cut(combined === "" ? "(no output)" : combined, maxOutput));
             }
             catch (error) {
-                return text(`Script failed: ${error instanceof Error ? error.message : String(error)}`, true);
+                return failure(`Script failed: ${error instanceof Error ? error.message : String(error)}`);
             }
             finally {
+                for (const controller of underway)
+                    controller.abort(); // calls still under way when the script ends are stopped
                 for (const handle of handles)
                     if (handle.alive)
                         handle.dispose();
@@ -158,6 +214,8 @@ export function codemodePlugin(options) {
     };
     return { name: "codemode", compensates: "one tool call per model request is slow and fills the context with intermediate results", setup: (api) => api.registerTool(runCode) };
 }
+/** Seconds for an error message: a whole number when it is one, otherwise one decimal (0.3 and not 0). */
+const seconds = (ms) => Number((ms / 1000).toFixed(1));
 function formatError(dumped) {
     if (typeof dumped === "object" && dumped !== null) {
         const { name, message } = dumped;

package/dist/packages/plugins/toolset/src/index.d.ts

@@ -2,5 +2,5 @@ export { searchPlugin } from "./search.js";
 export type { SearchOptions } from "./search.js";
 export { connectMcp } from "./mcp.js";
 export type { McpConnection, McpServerConfig, McpServerStatus } from "./mcp.js";
-export { codemodePlugin } from "./codemode.js";
+export { CODEMODE_TOOL, codemodePlugin } from "./codemode.js";
 export type { Authorize, CodemodeOptions } from "./codemode.js";

package/dist/packages/plugins/toolset/src/index.js

@@ -1,3 +1,3 @@
 export { searchPlugin } from "./search.js";
 export { connectMcp } from "./mcp.js";
-export { codemodePlugin } from "./codemode.js";
+export { CODEMODE_TOOL, codemodePlugin } from "./codemode.js";

package/dist/packages/plugins/trace/src/index.d.ts

@@ -0,0 +1,27 @@
+import type { Plugin } from "../../../kernel/src/index.js";
+/** One step of a run, tagged with the module that did the work. Written one per line to a trace file. */
+export interface TraceRecord {
+    /** Milliseconds since the trace began. */
+    t: number;
+    /** Module id, matching the node ids of the architecture diagram. */
+    module: string;
+    /** What happened (the event type). */
+    fn: string;
+    /** A short detail, never message text. */
+    detail?: string;
+}
+export interface TraceOptions {
+    /** Append records to this file as JSON lines. */
+    file?: string;
+    /** Receive each record. */
+    sink?(record: TraceRecord): void;
+    now?: () => number;
+}
+export interface TracePlugin extends Plugin {
+    records: TraceRecord[];
+}
+/**
+ * Records what runs, for the module map. It only watches events, never changes anything the model sees,
+ * and keeps no message text. A development aid, off unless added.
+ */
+export declare function tracePlugin(options?: TraceOptions): TracePlugin;

package/dist/packages/plugins/trace/src/index.js

@@ -0,0 +1,29 @@
+import { appendFileSync, mkdirSync } from "node:fs";
+import { dirname } from "node:path";
+import { moduleOf } from "./modules.js";
+/**
+ * Records what runs, for the module map. It only watches events, never changes anything the model sees,
+ * and keeps no message text. A development aid, off unless added.
+ */
+export function tracePlugin(options = {}) {
+    const now = options.now ?? Date.now;
+    const started = now();
+    const records = [];
+    if (options.file)
+        mkdirSync(dirname(options.file), { recursive: true });
+    return {
+        name: "trace",
+        compensates: "nothing: it only watches",
+        records,
+        setup(api) {
+            api.on("event", (event) => {
+                const { module, detail } = moduleOf(event);
+                const record = { t: now() - started, module, fn: event.type, ...(detail !== undefined ? { detail } : {}) };
+                records.push(record);
+                options.sink?.(record);
+                if (options.file)
+                    appendFileSync(options.file, `${JSON.stringify(record)}\n`);
+            });
+        },
+    };
+}

package/dist/packages/plugins/trace/src/modules.d.ts

@@ -0,0 +1,6 @@
+import type { Event } from "../../../kernel/src/index.js";
+/** Which module does the work behind each kind of event. */
+export declare function moduleOf(event: Event): {
+    module: string;
+    detail?: string;
+};

package/dist/packages/plugins/trace/src/modules.js

@@ -0,0 +1,28 @@
+/** Which module does the work behind each kind of event. */
+export function moduleOf(event) {
+    switch (event.type) {
+        case "run_start":
+        case "run_end":
+        case "turn_start":
+        case "turn_end":
+        case "paused":
+            return { module: "kernel", ...(event.type === "run_end" ? { detail: event.reason } : event.type === "paused" ? { detail: event.reason } : {}) };
+        case "message_start":
+        case "message_update":
+        case "reasoning_update":
+        case "message_reset":
+        case "message_end":
+            return { module: "llm" };
+        case "tool_start":
+        case "tool_end":
+            return { module: "tools", detail: event.call.name };
+        case "compaction":
+            return { module: "compaction" };
+        case "goal":
+            return { module: "goal", detail: event.status };
+        case "signal":
+            return { module: "kernel", detail: "signal" };
+        case "plugin":
+            return { module: `plugin-${event.name}` };
+    }
+}

package/dist/packages/session/src/file-log.d.ts

@@ -1,10 +1,15 @@
-import type { LogOptions, RewindableLog } from "./memory-log.js";
+import type { LogOptions, RewindableLog } from "./log-core.js";
 export interface SessionHeader {
     type: "header";
     version: number;
     id: string;
     cwd: string;
     ts: number;
+    /** Set on a session that was made by forking another: the entry it was copied up to, and the session it came from when that is known. */
+    forkedFrom?: {
+        entry: string;
+        session?: string;
+    };
 }
 export interface FileLog extends RewindableLog {
     header: SessionHeader;

package/dist/packages/session/src/file-log.js

@@ -1,7 +1,7 @@
 import { randomUUID } from "node:crypto";
 import { appendFile, mkdir, open, readFile, rm, truncate, writeFile } from "node:fs/promises";
 import { dirname } from "node:path";
-import { projectMessages } from "./projection.js";
+import { createLog } from "./log-core.js";
 import { createTree } from "./tree.js";
 const FORMAT_VERSION = 1;
 function isProcessAlive(pid) {
@@ -34,6 +34,7 @@ function parseFile(text) {
     const complete = lines.slice(0, -1); // the last piece has no trailing newline: it is empty or a torn write
     let header;
     const entries = [];
+    let rewoundTo;
     let validBytes = 0;
     for (const [index, line] of complete.entries()) {
         let value;
@@ -50,14 +51,18 @@ function parseFile(text) {
             if (header.version > FORMAT_VERSION)
                 throw new Error(`session file version ${header.version} is newer than supported`);
         }
+        else if (value.type === "rewind") {
+            rewoundTo = value.to;
+        }
         else {
             entries.push(value);
+            rewoundTo = undefined;
         }
         validBytes += Buffer.byteLength(line) + 1;
     }
     if (!header)
         throw new Error("corrupt session file: missing header");
-    return { header, entries, validBytes };
+    return { header, entries, validBytes, ...(rewoundTo !== undefined ? { rewoundTo } : {}) };
 }
 /**
  * One JSONL file per session: a header line, then one complete entry per line.
@@ -71,6 +76,8 @@ export async function openFileLog(path, options = {}) {
     await acquireLock(lockPath);
     let header;
     let entries;
+    let rewoundTo;
+    let size; // bytes of the file that are known to be good
     try {
         const existing = await readFile(path, "utf8").catch((error) => {
             if (error.code === "ENOENT")
@@ -79,15 +86,19 @@ export async function openFileLog(path, options = {}) {
         });
         if (existing === undefined || existing === "") {
             header = { type: "header", version: FORMAT_VERSION, id: newId(), cwd: options.cwd ?? process.cwd(), ts: now() };
-            await writeFile(path, `${JSON.stringify(header)}\n`);
+            const line = `${JSON.stringify(header)}\n`;
+            await writeFile(path, line);
             entries = [];
+            size = Buffer.byteLength(line);
         }
         else {
             const parsed = parseFile(existing);
             header = parsed.header;
             entries = parsed.entries;
-            if (parsed.validBytes < Buffer.byteLength(existing))
-                await truncate(path, parsed.validBytes);
+            rewoundTo = parsed.rewoundTo;
+            size = parsed.validBytes;
+            if (size < Buffer.byteLength(existing))
+                await truncate(path, size);
         }
     }
     catch (error) {
@@ -95,29 +106,38 @@ export async function openFileLog(path, options = {}) {
         throw error;
     }
     const tree = createTree(entries);
-    let writing = Promise.resolve();
+    if (rewoundTo !== undefined && (rewoundTo === null || entries.some((entry) => entry.id === rewoundTo)))
+        tree.moveLeaf(rewoundTo);
+    // A write that fails can leave half a line behind. The next write first cuts the file back to what is known to be good, so that half line
+    // never ends up in the middle of the file where it would make the whole session unreadable.
+    let damaged = false;
+    async function write(line) {
+        try {
+            if (damaged) {
+                await truncate(path, size);
+                damaged = false;
+            }
+            await appendFile(path, line);
+            size += Buffer.byteLength(line);
+        }
+        catch (error) {
+            damaged = true;
+            throw error;
+        }
+    }
+    const log = createLog(tree, {
+        saveEntry: (entry) => write(`${JSON.stringify(entry)}\n`),
+        saveRewind: (to) => write(`${JSON.stringify({ type: "rewind", to })}\n`),
+    }, options);
     return {
         header,
-        async append(body) {
-            const entry = { ...body, id: newId(), parentId: tree.leaf(), ts: now() };
-            tree.add(entry);
-            writing = writing.then(() => appendFile(path, `${JSON.stringify(entry)}\n`));
-            await writing;
-            return entry;
-        },
-        async branch() {
-            return tree.branch();
-        },
-        async project(upTo) {
-            const branch = tree.branch();
-            return projectMessages(upTo === undefined
-                ? branch
-                : branch.slice(0, Math.max(0, branch.findIndex((entry) => entry.id === upTo))));
-        },
-        rewindTo: (entryId) => tree.moveLeaf(entryId),
-        leaf: () => tree.leaf(),
+        append: log.append,
+        branch: log.branch,
+        project: log.project,
+        rewindTo: log.rewindTo,
+        leaf: log.leaf,
         async close() {
-            await writing;
+            await log.settled();
             await rm(lockPath, { force: true });
         },
     };

package/dist/packages/session/src/fork.d.ts

@@ -0,0 +1,16 @@
+import type { Log } from "../../kernel/src/index.js";
+import type { SessionHeader } from "./file-log.js";
+export interface ForkOptions {
+    /** The last entry to copy, an id from `log.branch()`. Left out, the whole current branch is copied. */
+    upTo?: string;
+    /** The working directory to record in the new session. Default: this process's. */
+    cwd?: string;
+    /** The id of the session the log comes from, if it has one; recorded so that the new session says where it came from. */
+    sessionId?: string;
+}
+/**
+ * Copies the conversation up to a point into a new session file, which is then a session of its own: its entries are the same entries (same ids, same
+ * parents), so what the model is sent from it is exactly what it was sent from the original at that point, and a provider's prompt cache still applies.
+ * The source is only read. The file appears whole or not at all, and an existing file is never replaced.
+ */
+export declare function forkLog(log: Log, path: string, options?: ForkOptions): Promise<SessionHeader>;

package/dist/packages/session/src/fork.js

@@ -0,0 +1,70 @@
+import { randomUUID } from "node:crypto";
+import { link, mkdir, unlink, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+/** Where to stop copying so that no turn is cut in two: after the results that answer the calls of the last assistant message that was copied. */
+function endOfTurn(branch, last) {
+    let assistant = -1;
+    for (let index = last; index >= 0; index--) {
+        const entry = branch[index];
+        if (entry?.type === "message" && entry.message.role === "assistant") {
+            assistant = index;
+            break;
+        }
+    }
+    const opened = assistant >= 0 ? branch[assistant] : undefined;
+    if (opened?.type !== "message")
+        return last;
+    const open = new Set(opened.message.content.flatMap((part) => (part.type === "tool_call" ? [part.id] : [])));
+    for (let index = assistant + 1; index <= last; index++) {
+        const entry = branch[index];
+        if (entry?.type === "message" && entry.message.toolCallId)
+            open.delete(entry.message.toolCallId);
+    }
+    let end = last;
+    while (open.size > 0 && end + 1 < branch.length) {
+        const next = branch[end + 1];
+        if (next.type === "message" && next.message.role !== "tool")
+            break; // a new turn begins: calls that were never answered stay as they were in the source
+        end++;
+        if (next.type === "message" && next.message.toolCallId)
+            open.delete(next.message.toolCallId);
+    }
+    return end;
+}
+/**
+ * Copies the conversation up to a point into a new session file, which is then a session of its own: its entries are the same entries (same ids, same
+ * parents), so what the model is sent from it is exactly what it was sent from the original at that point, and a provider's prompt cache still applies.
+ * The source is only read. The file appears whole or not at all, and an existing file is never replaced.
+ */
+export async function forkLog(log, path, options = {}) {
+    const branch = await log.branch();
+    let last = branch.length - 1;
+    if (options.upTo !== undefined) {
+        last = branch.findIndex((entry) => entry.id === options.upTo);
+        if (last === -1)
+            throw new Error(`entry ${options.upTo} is not on the current branch`);
+    }
+    const copied = branch.slice(0, endOfTurn(branch, last) + 1);
+    const header = {
+        type: "header",
+        version: 1,
+        id: randomUUID().slice(0, 8),
+        cwd: options.cwd ?? process.cwd(),
+        ts: Date.now(),
+        ...(copied.length > 0 ? { forkedFrom: { entry: copied.at(-1).id, ...(options.sessionId !== undefined ? { session: options.sessionId } : {}) } } : {}),
+    };
+    const text = [header, ...copied].map((line) => `${JSON.stringify(line)}\n`).join("");
+    await mkdir(dirname(path), { recursive: true });
+    const temporary = `${path}.${randomUUID().slice(0, 8)}.tmp`;
+    try {
+        await writeFile(temporary, text, { flag: "wx" });
+        // a hard link fails if the target exists, so a session that is there is never replaced, and the new one never shows up half written
+        await link(temporary, path).catch((error) => {
+            throw error.code === "EEXIST" ? new Error(`${path} already exists`) : error;
+        });
+    }
+    finally {
+        await unlink(temporary).catch(() => undefined);
+    }
+    return header;
+}

package/dist/packages/session/src/index.d.ts

@@ -1,4 +1,6 @@
 export { createMemoryLog } from "./memory-log.js";
 export type { LogOptions, RewindableLog } from "./memory-log.js";
 export { openFileLog } from "./file-log.js";
+export { forkLog } from "./fork.js";
+export type { ForkOptions } from "./fork.js";
 export type { FileLog, SessionHeader } from "./file-log.js";

package/dist/packages/session/src/index.js

@@ -1,2 +1,3 @@
 export { createMemoryLog } from "./memory-log.js";
 export { openFileLog } from "./file-log.js";
+export { forkLog } from "./fork.js";

package/dist/packages/session/src/log-core.d.ts

@@ -0,0 +1,37 @@
+import type { EntryBody, Log, LogEntry } from "../../kernel/src/index.js";
+import type { createTree } from "./tree.js";
+export interface LogOptions {
+    now?: () => number;
+    newId?: () => string;
+}
+/** A session log that can go back to an earlier entry and carry on from there. */
+export interface RewindableLog extends Log {
+    /** Moves the end of the conversation back to an earlier entry (or to the very start with null). Later entries start a new branch. */
+    rewindTo(entryId: string | null): void;
+    /** Id of the entry the next one will follow. */
+    leaf(): string | null;
+}
+/** Where a log keeps its entries. A memory log keeps them nowhere else. */
+export interface Storage {
+    /** Makes the entry durable. If this fails the entry is not part of the log. */
+    saveEntry(entry: LogEntry): Promise<void>;
+    /** Records that the end of the conversation moved. Best effort: the next entry carries the same information, so a lost record only matters if nothing follows. */
+    saveRewind(to: string | null): Promise<void>;
+}
+/**
+ * The one implementation of "a log": entries in a tree, one leaf, appends in order. The log is only as durable as its storage, and a log and its
+ * storage never disagree: an entry joins the tree after it is saved, and an append that fails changes nothing and does not stop the ones after it.
+ */
+export declare function createLog(tree: ReturnType<typeof createTree>, storage: Storage, options?: LogOptions): {
+    /** Resolves when everything started so far has been saved or has failed. */
+    settled: () => Promise<undefined>;
+    append(body: EntryBody): Promise<LogEntry>;
+    branch(): Promise<LogEntry[]>;
+    project(upTo?: string): Promise<import("../../kernel/src/index.js").Message[]>;
+    /**
+     * Takes effect at once. Entries that were already waiting to be saved follow the new end, so do not rewind while appends are in flight
+     * (the kernel does not: one run at a time, and it waits for each append).
+     */
+    rewindTo(entryId: string | null): void;
+    leaf: () => string | null;
+};