@giovannijecha/jecode 0.8.3 → 0.8.4

package/README.md

@@ -175,8 +175,9 @@ configuration, and safety boundaries.
 
 Public pull requests are not accepted at this stage. Code changes remain a
 maintainer and invited-collaborator workflow. See
-[CONTRIBUTING.md](CONTRIBUTING.md) and
-[CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md).
+[CONTRIBUTING.md](https://github.com/giovannijecha/jecode/blob/main/CONTRIBUTING.md)
+and
+[CODE_OF_CONDUCT.md](https://github.com/giovannijecha/jecode/blob/main/CODE_OF_CONDUCT.md).
 
 ## License
 

package/assets/wordmark-steel.svg

@@ -0,0 +1,3 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 760 180" role="img" aria-label="jecode">
+  <text x="380" y="128" fill="#669BD2" font-family="Inter,Nunito Sans,system-ui,sans-serif" font-size="132" font-weight="650" letter-spacing="-7" text-anchor="middle">jecode</text>
+</svg>

package/dist/batch.js

@@ -14,6 +14,7 @@ import { columns } from "./ui/render.js";
 import { terminalText } from "./ui/terminal-text.js";
 import { recordAuxiliaryUsage, recordRequestInput, recordUsage } from "./usage.js";
 import { assertPromptLength, boundedInputLines } from "./input-boundary.js";
+import { providerFailure } from "./provider-errors.js";
 export async function runBatch(session, environment = {}) {
     const write = environment.write ?? ((text) => stdout.write(text));
     const width = environment.width ?? columns();
@@ -115,7 +116,18 @@ export async function runBatch(session, environment = {}) {
                     commit(checkpoint, settlement);
                 return compacted;
             };
-            await runTurn(history, options(session, policy), turn, signal, modelHistory);
+            try {
+                await runTurn(history, options(session, policy), turn, signal, modelHistory);
+            }
+            catch (error) {
+                throwIfAborted(signal);
+                if (!(error instanceof Error))
+                    throw error;
+                const message = providerFailure(session.provider, error);
+                if (message === error.message)
+                    throw error;
+                throw new Error(message, { cause: error });
+            }
             turn.flush();
         }
         throwIfAborted(signal);

package/dist/config.js

@@ -43,9 +43,7 @@ export function loadConfig(argv, saved = readSettings()) {
             : { maxModelRequests: toInt(maxModelRequests, "max-steps") }),
         compactionPercent: toPercent(pick(flags["compaction-percent"], process.env.JECODE_COMPACTION_PERCENT, String(saved.compactionPercent ?? DEFAULT_COMPACTION_PERCENT))),
         root: path.resolve(pick(flags.root, undefined, process.cwd())),
-        autoApprove: flags["auto-approve"] === "true" ||
-            flags["auto-approve"] === "1" ||
-            process.env.JECODE_AUTO_APPROVE === "1",
+        autoApprove: autoApproval(flags["auto-approve"], process.env.JECODE_AUTO_APPROVE),
         ephemeral: bool(flags.ephemeral, process.env.JECODE_EPHEMERAL, false),
     };
 }
@@ -56,6 +54,11 @@ function bool(flag, env, fallback) {
         return env === "true" || env === "1";
     return fallback;
 }
+function autoApproval(flag, env) {
+    if (flag !== undefined)
+        return flag === "true" || flag === "1";
+    return env === "1";
+}
 function pick(flag, env, fallback) {
     if (flag !== undefined && flag !== "")
         return flag;

package/dist/provider-commands.js

@@ -15,28 +15,65 @@ export async function providersCommand(session, host) {
     const choose = chooser(host);
     if (choose === undefined)
         return;
-    let selected = Math.max(0, PROVIDERS.findIndex((provider) => provider.id === session.provider.id));
+    const groups = providerGroups();
+    let selected = Math.max(0, groups.findIndex((group) => group.providers.some((provider) => provider.id === session.provider.id)));
     while (true) {
         const index = await choose({
             title: [],
-            options: PROVIDERS.map((provider) => ({
+            options: groups.map((group) => ({
+                label: group.label,
+                value: providerCount(group.providers.length),
+            })),
+            index: selected,
+        });
+        if (index === undefined) {
+            throwIfAborted(host.signal);
+            return;
+        }
+        const group = groups[index];
+        if (group === undefined)
+            return;
+        selected = index;
+        await providerGroupCommand(group, session, host);
+        throwIfAborted(host.signal);
+    }
+}
+function providerGroups() {
+    return [
+        { label: "Account", providers: PROVIDERS.filter((provider) => provider.auth.kind === "oauth") },
+        { label: "API", providers: PROVIDERS.filter((provider) => provider.auth.kind !== "oauth") },
+    ];
+}
+async function providerGroupCommand(group, session, host) {
+    if (host.choose === undefined)
+        return;
+    let selected = Math.max(0, group.providers.findIndex((provider) => provider.id === session.provider.id));
+    while (true) {
+        const index = await host.choose({
+            title: heading(group.label, "provider access", session.palette),
+            options: group.providers.map((provider) => ({
                 label: providerLabel(provider.id),
                 value: providerAccessHint(provider),
             })),
             index: selected,
         });
-        if (index === undefined)
+        if (index === undefined) {
+            throwIfAborted(host.signal);
             return;
-        const provider = PROVIDERS[index];
+        }
+        const provider = group.providers[index];
         if (provider === undefined)
             return;
         selected = index;
         await manageProvider(provider, session, host);
-        // Esc closes only the nested provider flow. Ctrl+C also settles that
-        // picker, but aborts the command signal and must not reopen the parent.
+        // Esc closes only the provider-specific flow. Ctrl+C also settles that
+        // interaction, but aborts the command signal and must not reopen a menu.
         throwIfAborted(host.signal);
     }
 }
+function providerCount(count) {
+    return `${count} ${count === 1 ? "provider" : "providers"}`;
+}
 export function providerAccessHint(provider) {
     if (provider.id === "ollama") {
         const connection = ollamaConnection();

package/dist/provider-errors.js

@@ -1,11 +1,69 @@
 // Actionable provider failures for user-facing command and turn surfaces.
+import { redactCredentials } from "./credential-safety.js";
 import { providerLabel } from "./provider-label.js";
+import { leadingText } from "./text-boundary.js";
+import { terminalText } from "./ui/terminal-text.js";
 const CONNECTION_FAILURE = /network error calling|timed out waiting for response headers|response body was idle/i;
+const MAX_MESSAGE_CHARS = 1_000;
+const MAX_REASON_CHARS = 500;
+const HTML = /<!doctype\s|<\/?[a-z][^>]*>/i;
 export function providerFailure(provider, error, labelProvider = false) {
     if (provider.id === "ollama" && CONNECTION_FAILURE.test(error.message)) {
         return provider.location?.() === "local"
             ? "Ollama is not reachable on this computer · start Ollama or choose cloud in /providers"
             : "Ollama is not reachable · check its connection in /providers";
     }
-    return labelProvider ? `${providerLabel(provider.id)}: ${error.message}` : error.message;
+    const message = safeText(error.message, MAX_MESSAGE_CHARS) || "provider request failed";
+    const reason = providerReason(error);
+    const detail = reason !== undefined && !message.toLocaleLowerCase().includes(reason.toLocaleLowerCase())
+        ? ` · ${reason}`
+        : "";
+    const failure = `${message}${detail}`;
+    return labelProvider ? `${providerLabel(provider.id)}: ${failure}` : failure;
+}
+function providerReason(error) {
+    const body = error.body;
+    if (typeof body !== "string" || body.trim() === "")
+        return undefined;
+    let parsed;
+    try {
+        parsed = JSON.parse(body);
+    }
+    catch {
+        const raw = body.trim();
+        if (raw.startsWith("{") || raw.startsWith("[") || HTML.test(raw))
+            return undefined;
+        return safeReason(raw);
+    }
+    for (const candidate of reasonCandidates(parsed)) {
+        const reason = safeReason(candidate);
+        if (reason !== undefined)
+            return reason;
+    }
+    return undefined;
+}
+function reasonCandidates(value) {
+    if (typeof value === "string")
+        return [value];
+    if (!record(value))
+        return [];
+    const error = value["error"];
+    return [
+        record(error) ? error["message"] : undefined,
+        typeof error === "string" ? error : undefined,
+        value["message"],
+        value["detail"],
+    ].filter((candidate) => typeof candidate === "string");
+}
+function safeReason(text) {
+    if (HTML.test(text))
+        return undefined;
+    return safeText(text, MAX_REASON_CHARS) || undefined;
+}
+function safeText(text, max) {
+    const redacted = redactCredentials(text).trim().replace(/\s+/gu, " ");
+    return leadingText(terminalText(redacted), max);
+}
+function record(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
 }

package/dist/providers/http.js

@@ -40,7 +40,10 @@ export async function postSse(url, headers, body, maxOutputTokens, signal, onSta
     const res = await request(url, { accept: "text/event-stream", ...headers }, body, signal, onStatus);
     if (res.body === null)
         throw httpError(`${url} returned no body`, res.status);
-    return readSseJson(withIdleTimeout(url, res.body), maximumChars);
+    return readSseJson(res.body, maximumChars, {
+        milliseconds: BODY_IDLE_TIMEOUT_MS,
+        error: () => httpError(`${url} SSE stream was idle for ${BODY_IDLE_TIMEOUT_MS}ms without an event`, res.status),
+    });
 }
 async function request(url, headers, body, signal, onStatus) {
     const maxRetries = body === undefined ? GET_RETRIES : 0;
@@ -154,39 +157,6 @@ async function timedRead(url, reader) {
             clearTimeout(timer);
     }
 }
-function withIdleTimeout(url, body) {
-    const reader = body.getReader();
-    let released = false;
-    const release = () => {
-        if (released)
-            return;
-        released = true;
-        reader.releaseLock();
-    };
-    return new ReadableStream({
-        async pull(controller) {
-            try {
-                const { done, value } = await timedRead(url, reader);
-                if (done) {
-                    release();
-                    controller.close();
-                }
-                else {
-                    controller.enqueue(value);
-                }
-            }
-            catch (error) {
-                await reader.cancel(error).catch(() => undefined);
-                release();
-                controller.error(error);
-            }
-        },
-        async cancel(reason) {
-            await reader.cancel(reason).catch(() => undefined);
-            release();
-        },
-    });
-}
 function waitLabel(ms) {
     return ms < 1_000 ? `${ms}ms` : `${Math.ceil(ms / 1_000)}s`;
 }

package/dist/providers/openai-codex.js

@@ -72,7 +72,7 @@ export const openaiCodex = {
                 include: ["reasoning.encrypted_content"],
                 prompt_cache_key: SESSION_ID,
             }, req.maxTokens, req.signal, req.onStatus);
-            const data = await assembleOpenAI(events, req.onStream);
+            const data = await assembleOpenAI(events, req.onStream, req.onStatus);
             const notice = stopNotice(data);
             if (notice !== undefined)
                 req.onStream?.({ kind: "text", text: `\n${notice}` });

package/dist/providers/openai-stream.js

@@ -4,40 +4,70 @@
 // response in `response.completed`. The ChatGPT Codex backend can instead send
 // an empty final `output` after complete `response.output_item.done` events, so
 // those streamed items remain the fallback when the final envelope is empty.
-export async function assembleOpenAI(events, onStream) {
+export async function assembleOpenAI(events, onStream, onStatus) {
     const items = [];
     const announcedTools = { identities: new Set(), anonymous: false };
     let refusal = false;
+    let activity;
+    const status = (next) => {
+        if (activity === next)
+            return;
+        activity = next;
+        onStatus?.(next);
+    };
     for await (const raw of events) {
         const event = raw;
         switch (event.type) {
+            case "response.created":
+            case "response.in_progress":
+                if (activity === undefined)
+                    status("Working");
+                break;
             case "response.output_text.delta":
-                if (typeof event.delta === "string")
+                if (typeof event.delta === "string") {
+                    status("Responding");
                     onStream?.({ kind: "text", text: event.delta });
+                }
                 break;
             case "response.refusal.delta":
                 if (typeof event.delta === "string") {
+                    status("Responding");
                     onStream?.({ kind: "text", text: `${refusal ? "" : "[refused] "}${event.delta}` });
                     refusal = true;
                 }
                 break;
             case "response.reasoning_summary_text.delta":
-                if (typeof event.delta === "string")
+                if (typeof event.delta === "string") {
+                    status("Thinking");
                     onStream?.({ kind: "thinking", text: event.delta });
+                }
+                break;
+            case "response.reasoning_summary_part.added":
+                status("Thinking");
+                break;
+            case "response.reasoning_summary_text.done":
+            case "response.reasoning_summary_part.done":
+                status("Working");
                 break;
             case "response.output_item.added":
                 if (isFunctionCall(event.item)) {
-                    announceTool(event, event.item, announcedTools, onStream);
+                    announceTool(event, event.item, announcedTools, onStream, status);
+                }
+                else if (itemType(event.item) === "reasoning") {
+                    status("Thinking");
+                }
+                else if (itemType(event.item) === "message") {
+                    status("Responding");
                 }
                 break;
             case "response.function_call_arguments.delta":
             case "response.function_call_arguments.done":
-                announceTool(event, undefined, announcedTools, onStream);
+                announceTool(event, undefined, announcedTools, onStream, status);
                 break;
             case "response.output_item.done":
                 if (event.item !== undefined) {
                     if (isFunctionCall(event.item)) {
-                        announceTool(event, event.item, announcedTools, onStream);
+                        announceTool(event, event.item, announcedTools, onStream, status);
                     }
                     items.push(event.item);
                 }
@@ -66,7 +96,12 @@ function isFunctionCall(item) {
     return typeof item === "object" && item !== null &&
         item["type"] === "function_call";
 }
-function announceTool(event, item, announced, onStream) {
+function itemType(item) {
+    return typeof item === "object" && item !== null
+        ? item["type"]
+        : undefined;
+}
+function announceTool(event, item, announced, onStream, onStatus) {
     const identities = toolIdentities(event, item);
     if (identities.length === 0) {
         if (announced.anonymous)
@@ -82,6 +117,7 @@ function announceTool(event, item, announced, onStream) {
     }
     const rawName = item?.name ?? event.name;
     const name = typeof rawName === "string" && rawName !== "" ? rawName : undefined;
+    onStatus?.(`Preparing ${name ?? "tool"}`);
     onStream?.({ kind: "tool", ...(name === undefined ? {} : { name }) });
 }
 function toolIdentities(event, item) {

package/dist/providers/openai.js

@@ -87,7 +87,7 @@ export const openai = {
             include: ["reasoning.encrypted_content"],
             stream: true,
         }, req.maxTokens, req.signal, req.onStatus);
-        const data = await assembleOpenAI(events, req.onStream);
+        const data = await assembleOpenAI(events, req.onStream, req.onStatus);
         const notice = stopNotice(data);
         if (notice !== undefined)
             req.onStream?.({ kind: "text", text: `\n${notice}` });

package/dist/providers/sse.js

@@ -4,31 +4,44 @@
 // `data` matters here — both providers put the event discriminator inside the
 // JSON payload, so the `event:` line is redundant and skipped.
 import { addBounded, MAX_SSE_EVENT_CHARS, } from "./stream-limits.js";
-export async function* readSseJson(body, maximumChars) {
+export async function* readSseJson(body, maximumChars, idle) {
     const reader = body.getReader();
     const decoder = new TextDecoder();
     const parser = new SseEventParser();
     let finished = false;
     let total = 0;
     try {
-        for (;;) {
-            const { done, value } = await reader.read();
-            if (done)
-                break;
-            const text = decoder.decode(value, { stream: true });
-            total = addBounded(total, text.length, maximumChars, "SSE stream");
-            for (const payload of parser.push(text))
+        let ended = false;
+        while (!ended) {
+            // One deadline spans every raw read until a complete JSON event lands.
+            // SSE comments and partial framing prove only that the socket is alive;
+            // they must not keep a model request pending forever.
+            const deadline = eventDeadline(idle);
+            const payloads = [];
+            try {
+                while (payloads.length === 0 && !ended) {
+                    const { done, value } = await deadline.wait(reader.read());
+                    if (done) {
+                        ended = true;
+                        const text = decoder.decode();
+                        total = addBounded(total, text.length, maximumChars, "SSE stream");
+                        payloads.push(...parser.push(text));
+                        const payload = parser.finish();
+                        if (payload !== undefined)
+                            payloads.push(payload);
+                        continue;
+                    }
+                    const text = decoder.decode(value, { stream: true });
+                    total = addBounded(total, text.length, maximumChars, "SSE stream");
+                    payloads.push(...parser.push(text));
+                }
+            }
+            finally {
+                deadline.clear();
+            }
+            for (const payload of payloads)
                 yield payload;
         }
-        // A stream that ends without a trailing blank line still owes us its last
-        // event.
-        const text = decoder.decode();
-        total = addBounded(total, text.length, maximumChars, "SSE stream");
-        for (const payload of parser.push(text))
-            yield payload;
-        const payload = parser.finish();
-        if (payload !== undefined)
-            yield payload;
         finished = true;
     }
     finally {
@@ -37,6 +50,21 @@ export async function* readSseJson(body, maximumChars) {
         reader.releaseLock();
     }
 }
+function eventDeadline(idle) {
+    if (idle === undefined)
+        return { wait: (pending) => pending, clear: () => undefined };
+    let timer;
+    const expired = new Promise((_resolve, reject) => {
+        timer = setTimeout(() => reject(idle.error()), idle.milliseconds);
+    });
+    return {
+        wait: (pending) => Promise.race([pending, expired]),
+        clear: () => {
+            if (timer !== undefined)
+                clearTimeout(timer);
+        },
+    };
+}
 // Keep fragments in bounded groups. A provider may split one SSE line into
 // hundreds of thousands of tiny chunks; repeatedly flattening the growing line
 // would make parsing quadratic even if boundary scanning itself were linear.

package/dist/sessions/catalog.js

@@ -0,0 +1,199 @@
+// Small, head-tied projections for the resume catalogue.
+//
+// Conversation nodes remain authoritative and are fully decoded when a
+// session is selected. This auxiliary record lets listing stay independent of
+// every unselected tree's depth; a missing or suspect record falls back to the
+// strict loader and can be rebuilt without changing the session schema.
+import { Buffer } from "node:buffer";
+import { CONVERSATION_LIMITS } from "../conversation.js";
+import { leadingText } from "../text-boundary.js";
+import { decodeHead, encodeHead } from "./codec.js";
+export const SESSION_CATALOG_FILE = "catalog.json";
+export const SESSION_CHECKPOINT_FILE = ".checkpoint";
+export const SESSION_CATALOG_BYTES = 4 * 1_024;
+const CATALOG_SCHEMA = 1;
+const PREVIEW_CODE_UNITS = 160;
+export function sessionCatalog(meta, head, conversation) {
+    assertActiveHead(head, conversation);
+    const resumable = conversation.latestResumable();
+    return own({
+        version: CATALOG_SCHEMA,
+        id: meta.id,
+        workspaceDigest: meta.workspaceDigest,
+        createdAt: meta.createdAt,
+        head,
+        resumeNodeId: resumable?.activeNodeId ?? 0,
+        turns: resumable === undefined ? 0 : selectedTurnCount(resumable),
+        preview: resumable === undefined ? "" : firstUserText(resumable),
+    });
+}
+/** Advance the common linear checkpoint path without walking prior turns. */
+export function advanceSessionCatalog(previous, meta, head, conversation) {
+    assertActiveHead(head, conversation);
+    if (previous.id !== meta.id ||
+        previous.workspaceDigest !== meta.workspaceDigest ||
+        previous.createdAt !== meta.createdAt)
+        throw new Error("session catalogue does not match its metadata");
+    const active = conversation.activeNode;
+    const revisesHead = active.id === previous.head.nodeId &&
+        active.parentId === previous.head.parentId &&
+        active.revision === previous.head.revision + 1;
+    const extendsHead = active.parentId === previous.head.nodeId &&
+        active.id > previous.head.nodeId && active.revision === 1;
+    if (!revisesHead && !extendsHead)
+        return sessionCatalog(meta, head, conversation);
+    // A resumable child of an unfinished head makes that intermediate node part
+    // of the selected path. Rebuild in that uncommon case so the turn count is
+    // exact instead of assuming one visible turn was appended.
+    if (extendsHead && active.settlement !== "checkpointed" &&
+        previous.resumeNodeId !== previous.head.nodeId)
+        return sessionCatalog(meta, head, conversation);
+    if (active.settlement === "checkpointed" && previous.resumeNodeId === active.id) {
+        return sessionCatalog(meta, head, conversation);
+    }
+    const resumable = active.settlement !== "checkpointed";
+    const addsTurn = resumable && previous.resumeNodeId !== active.id;
+    const turns = previous.turns + (addsTurn ? 1 : 0);
+    const preview = turns === 0
+        ? ""
+        : previous.turns === 0
+            ? firstUserTextInNode(active)
+            : previous.preview;
+    return own({
+        version: CATALOG_SCHEMA,
+        id: meta.id,
+        workspaceDigest: meta.workspaceDigest,
+        createdAt: meta.createdAt,
+        head,
+        resumeNodeId: resumable ? active.id : previous.resumeNodeId,
+        turns,
+        preview,
+    });
+}
+export function encodeSessionCatalog(catalog) {
+    const encoded = `${JSON.stringify(catalog, null, 2)}\n`;
+    decodeSessionCatalog(JSON.parse(encoded));
+    if (Buffer.byteLength(encoded, "utf8") > SESSION_CATALOG_BYTES) {
+        throw new Error("session catalogue data is invalid or unsupported");
+    }
+    return encoded;
+}
+export function decodeSessionCatalog(value) {
+    if (!record(value) || !keys(value, "createdAt,head,id,preview,resumeNodeId,turns,version,workspaceDigest"))
+        throw invalid();
+    const head = decodeHead(value["head"]);
+    const resumeNodeId = value["resumeNodeId"];
+    const turns = value["turns"];
+    const preview = value["preview"];
+    if (value["version"] !== CATALOG_SCHEMA ||
+        !identifier(value["id"]) ||
+        !digest(value["workspaceDigest"]) ||
+        !timestamp(value["createdAt"]) ||
+        !integer(resumeNodeId, 0) || resumeNodeId > head.nodeId ||
+        !integer(turns, 0) || turns > CONVERSATION_LIMITS.nodes || turns > resumeNodeId ||
+        typeof preview !== "string" || preview.length > PREVIEW_CODE_UNITS ||
+        (resumeNodeId === 0) !== (turns === 0) ||
+        (turns === 0 ? preview !== "" : preview === ""))
+        throw invalid();
+    return Object.freeze({
+        version: CATALOG_SCHEMA,
+        id: value["id"],
+        workspaceDigest: value["workspaceDigest"],
+        createdAt: value["createdAt"],
+        head,
+        resumeNodeId,
+        turns,
+        preview,
+    });
+}
+export function catalogMatches(catalog, meta, head) {
+    return catalog.id === meta.id &&
+        catalog.workspaceDigest === meta.workspaceDigest &&
+        catalog.createdAt === meta.createdAt &&
+        sameSessionHead(catalog.head, head);
+}
+export function sameSessionHead(left, right) {
+    return left.version === right.version &&
+        left.sequence === right.sequence &&
+        left.nodeId === right.nodeId &&
+        left.parentId === right.parentId &&
+        left.revision === right.revision &&
+        left.updatedAt === right.updatedAt;
+}
+function own(value) {
+    encodeHead(value.head);
+    return decodeSessionCatalog(structuredClone(value));
+}
+function assertActiveHead(head, conversation) {
+    const active = conversation.activeNode;
+    if (active === undefined || active.id !== head.nodeId ||
+        active.parentId !== head.parentId || active.revision !== head.revision)
+        throw new Error("session catalogue does not match its conversation head");
+}
+function selectedTurnCount(conversation) {
+    let count = 0;
+    let id = conversation.activeNodeId;
+    while (id !== 0) {
+        count++;
+        id = conversation.node(id)?.parentId ?? 0;
+    }
+    return count;
+}
+function firstUserText(conversation) {
+    const path = [];
+    let id = conversation.activeNodeId;
+    while (id !== 0) {
+        const node = conversation.node(id);
+        if (node === undefined)
+            throw new Error("session catalogue path is incomplete");
+        path.push(node);
+        id = node.parentId;
+    }
+    for (let index = path.length - 1; index >= 0; index--) {
+        const preview = userTextInNode(path[index]);
+        if (preview !== undefined)
+            return preview;
+    }
+    return "Untitled session";
+}
+function firstUserTextInNode(node) {
+    return userTextInNode(node) ?? "Untitled session";
+}
+function userTextInNode(node) {
+    for (const message of node.messages) {
+        if (message.role !== "user")
+            continue;
+        const preview = textPreview(message.content.find((block) => block.kind === "text")?.text);
+        if (preview !== undefined)
+            return preview;
+    }
+    return undefined;
+}
+function textPreview(text) {
+    const normalized = text?.replace(/\s+/gu, " ").trim();
+    return normalized === undefined || normalized === ""
+        ? undefined
+        : leadingText(normalized, PREVIEW_CODE_UNITS);
+}
+function keys(value, expected) {
+    return Object.keys(value).sort().join(",") === expected;
+}
+function record(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function integer(value, minimum) {
+    return typeof value === "number" && Number.isSafeInteger(value) && value >= minimum;
+}
+function identifier(value) {
+    return typeof value === "string" && /^[a-zA-Z0-9][a-zA-Z0-9._-]{0,127}$/.test(value);
+}
+function digest(value) {
+    return typeof value === "string" && /^[a-f0-9]{64}$/.test(value);
+}
+function timestamp(value) {
+    return typeof value === "string" && value.length >= 20 && value.length <= 64 &&
+        Number.isFinite(Date.parse(value));
+}
+function invalid() {
+    return new Error("session catalogue data is invalid or unsupported");
+}

package/dist/sessions/store.js

@@ -4,12 +4,12 @@
 // after that node is durable, so a crash leaves either the prior checkpoint or
 // one strictly recoverable mutation -- never an ambiguous partial history.
 import { createHash, randomUUID } from "node:crypto";
-import { chmod, lstat, mkdir, open, opendir, readFile, readdir, realpath, rename, rm, stat, } from "node:fs/promises";
+import { chmod, lstat, mkdir, open, opendir, readFile, readdir, realpath, rename, rm, } from "node:fs/promises";
 import * as path from "node:path";
 import { atomicWrite } from "../atomic.js";
 import { CONVERSATION_LIMITS, ConversationTree } from "../conversation.js";
-import { leadingText } from "../text-boundary.js";
 import { userDataPath } from "../user-data.js";
+import { advanceSessionCatalog, catalogMatches, decodeSessionCatalog, encodeSessionCatalog, sameSessionHead, sessionCatalog, SESSION_CATALOG_BYTES, SESSION_CATALOG_FILE, SESSION_CHECKPOINT_FILE, } from "./catalog.js";
 import { decodeHead, decodeMeta, decodeNode, encodeHead, encodeMeta, encodeNode, SESSION_FILE_LIMITS, SESSION_SCHEMA, } from "./codec.js";
 import { leaseOwner, leaseToken, pidIsAlive, removeLease, sessionLease, } from "./lease.js";
 const DIRECTORY_MODE = 0o700;
@@ -44,24 +44,7 @@ export class DurableSessionStore {
         for (let start = 0; start < names.length; start += CATALOG_READ_CONCURRENCY) {
             const batch = await Promise.all(names.slice(start, start + CATALOG_READ_CONCURRENCY)
                 .map(async (id) => {
-                try {
-                    const snapshot = await this.load(id);
-                    const conversation = snapshot.conversation.latestResumable();
-                    if (conversation === undefined)
-                        return undefined;
-                    return {
-                        id,
-                        createdAt: snapshot.meta.createdAt,
-                        updatedAt: snapshot.head.updatedAt,
-                        turns: selectedTurnCount(conversation),
-                        preview: firstUserText(conversation),
-                        active: await this.#leaseIsActive(id),
-                    };
-                }
-                catch {
-                    // Corrupt or foreign data never becomes a resume candidate.
-                    return undefined;
-                }
+                return await this.#catalogEntry(id);
             }));
             catalog.push(...batch.filter((entry) => entry !== undefined));
         }
@@ -74,9 +57,7 @@ export class DurableSessionStore {
         const directory = this.#sessionDirectory(id);
         await assertDirectory(directory);
         const meta = decodeMeta(await readJson(path.join(directory, "meta.json"), SESSION_FILE_LIMITS.metadataBytes));
-        if (meta.id !== id || meta.workspaceDigest !== this.workspaceDigest ||
-            workspaceKey(meta.workspaceRoot) !== workspaceKey(this.workspaceRoot))
-            throw new Error("session belongs to a different workspace");
+        assertSessionWorkspace(meta, id, this.workspaceRoot, this.workspaceDigest);
         let head = decodeHead(await readJson(path.join(directory, "head.json"), SESSION_FILE_LIMITS.metadataBytes));
         const stored = await readNodes(path.join(directory, "nodes"));
         const ahead = stored.filter((entry) => entry.sequence > head.sequence);
@@ -120,7 +101,8 @@ export class DurableSessionStore {
         }
         const nodes = stored.map((entry) => entry.node);
         const conversation = ConversationTree.restore(nodes, head.nodeId);
-        return Object.freeze({ meta, head, conversation });
+        const catalog = sessionCatalog(meta, head, conversation);
+        return Object.freeze({ meta, head, conversation, catalog });
     }
     async publish(conversation, claim) {
         const active = conversation.activeNode;
@@ -147,6 +129,7 @@ export class DurableSessionStore {
             revision: active.revision,
             updatedAt: now,
         });
+        const catalog = sessionCatalog(meta, head, conversation);
         try {
             await makePrivateDirectory(temporary);
             const nodes = path.join(temporary, "nodes");
@@ -157,6 +140,7 @@ export class DurableSessionStore {
             }
             await atomicWrite(path.join(temporary, "meta.json"), encodeMeta(meta), { mode: FILE_MODE });
             await atomicWrite(path.join(temporary, "head.json"), encodeHead(head), { mode: FILE_MODE });
+            await atomicWrite(path.join(temporary, SESSION_CATALOG_FILE), encodeSessionCatalog(catalog), { mode: FILE_MODE });
             if (token !== undefined) {
                 await atomicWrite(path.join(temporary, "active"), token, { mode: FILE_MODE });
             }
@@ -166,7 +150,7 @@ export class DurableSessionStore {
             await removeTemporaryDirectory(temporary, this.#bucket);
             throw error;
         }
-        const snapshot = Object.freeze({ meta, head, conversation });
+        const snapshot = Object.freeze({ meta, head, conversation, catalog });
         if (token === undefined)
             return snapshot;
         const lease = sessionLease(id, path.join(target, "active"), token);
@@ -184,7 +168,7 @@ export class DurableSessionStore {
         };
         await validateNodesDirectory();
         const currentHead = decodeHead(await readJson(path.join(directory, "head.json"), SESSION_FILE_LIMITS.metadataBytes));
-        if (!sameHead(currentHead, previous.head)) {
+        if (!sameSessionHead(currentHead, previous.head)) {
             throw new Error("session head changed after its verified snapshot");
         }
         const active = conversation.activeNode;
@@ -216,12 +200,19 @@ export class DurableSessionStore {
             revision: active.revision,
             updatedAt: now,
         });
+        const catalog = advanceSessionCatalog(previous.catalog, previous.meta, head, conversation);
+        const checkpointToken = leaseToken();
+        await atomicWrite(path.join(directory, SESSION_CHECKPOINT_FILE), checkpointToken, { mode: FILE_MODE, validate: async () => assertDirectory(directory) });
         await atomicWrite(path.join(nodesDirectory, nodeName(active.id)), encodeNode(active, head.sequence, now), { mode: FILE_MODE, validate: async () => validateNodesDirectory() });
         await atomicWrite(path.join(directory, "head.json"), encodeHead(head), {
             mode: FILE_MODE,
             validate: async () => assertDirectory(directory),
         });
-        return Object.freeze({ meta: previous.meta, head, conversation });
+        await this.#writeCatalog(previous.meta.id, catalog, checkpointToken).catch(() => undefined);
+        // Once the canonical head is durable, a missing summary is detectable by
+        // its head mismatch and can be rebuilt without retaining a live marker.
+        await removeLease(path.join(directory, SESSION_CHECKPOINT_FILE), checkpointToken);
+        return Object.freeze({ meta: previous.meta, head, conversation, catalog });
     }
     async claim(id) {
         assertSessionId(id);
@@ -265,6 +256,74 @@ export class DurableSessionStore {
         const owner = await leaseOwner(path.join(this.#sessionDirectory(id), "active"));
         return owner !== undefined && pidIsAlive(owner.pid);
     }
+    async #catalogEntry(id) {
+        try {
+            const directory = this.#sessionDirectory(id);
+            await assertDirectory(directory);
+            const checkpointFile = path.join(directory, SESSION_CHECKPOINT_FILE);
+            // A second head read closes the only useful race: a checkpoint landing
+            // between the small record reads. A changing marker gets one retry.
+            for (let attempt = 0; attempt < 2; attempt++) {
+                const checkpointBefore = await leaseOwner(checkpointFile);
+                try {
+                    const [metaValue, headValue, catalogValue] = await Promise.all([
+                        readJson(path.join(directory, "meta.json"), SESSION_FILE_LIMITS.metadataBytes),
+                        readJson(path.join(directory, "head.json"), SESSION_FILE_LIMITS.metadataBytes),
+                        readJson(path.join(directory, SESSION_CATALOG_FILE), SESSION_CATALOG_BYTES),
+                    ]);
+                    const meta = decodeMeta(metaValue);
+                    const head = decodeHead(headValue);
+                    const storedCatalog = decodeSessionCatalog(catalogValue);
+                    assertSessionWorkspace(meta, id, this.workspaceRoot, this.workspaceDigest);
+                    const confirmedHead = decodeHead(await readJson(path.join(directory, "head.json"), SESSION_FILE_LIMITS.metadataBytes));
+                    const checkpointAfter = await leaseOwner(checkpointFile);
+                    if (!sameLease(checkpointBefore, checkpointAfter))
+                        continue;
+                    if (!sameSessionHead(head, confirmedHead) ||
+                        !catalogMatches(storedCatalog, meta, head))
+                        break;
+                    if (checkpointAfter !== undefined && !pidIsAlive(checkpointAfter.pid))
+                        break;
+                    const active = await this.#leaseIsActive(id) || checkpointAfter !== undefined;
+                    return catalogEntry(storedCatalog, active);
+                }
+                catch {
+                    break;
+                }
+            }
+            // Missing, stale, or malformed summaries are rebuilt only while the
+            // session is idle. Selecting a session still performs this strict load.
+            const checkpoint = await leaseOwner(checkpointFile);
+            if (await this.#leaseIsActive(id) ||
+                (checkpoint !== undefined && pidIsAlive(checkpoint.pid)))
+                return undefined;
+            const snapshot = await this.load(id);
+            await this.#writeCatalog(id, snapshot.catalog, checkpoint?.token).catch(() => undefined);
+            const currentCheckpoint = await leaseOwner(checkpointFile);
+            const active = await this.#leaseIsActive(id) ||
+                (currentCheckpoint !== undefined && pidIsAlive(currentCheckpoint.pid));
+            return catalogEntry(snapshot.catalog, active);
+        }
+        catch {
+            // Corrupt, unsafe, active-without-a-summary, or foreign data never
+            // becomes a resume candidate.
+            return undefined;
+        }
+    }
+    async #writeCatalog(id, catalog, checkpointToken) {
+        const directory = this.#sessionDirectory(id);
+        const validate = async () => {
+            await assertDirectory(directory);
+            const currentHead = decodeHead(await readJson(path.join(directory, "head.json"), SESSION_FILE_LIMITS.metadataBytes));
+            if (!sameSessionHead(currentHead, catalog.head)) {
+                throw new Error("session head changed while updating its catalogue");
+            }
+        };
+        await atomicWrite(path.join(directory, SESSION_CATALOG_FILE), encodeSessionCatalog(catalog), { mode: FILE_MODE, validate });
+        if (checkpointToken !== undefined) {
+            await removeLease(path.join(directory, SESSION_CHECKPOINT_FILE), checkpointToken);
+        }
+    }
 }
 async function catalogNames(directory) {
     try {
@@ -288,6 +347,26 @@ async function catalogNames(directory) {
     }
     return names.sort((left, right) => right.localeCompare(left));
 }
+function catalogEntry(catalog, active) {
+    if (catalog.resumeNodeId === 0)
+        return undefined;
+    return Object.freeze({
+        id: catalog.id,
+        createdAt: catalog.createdAt,
+        updatedAt: catalog.head.updatedAt,
+        turns: catalog.turns,
+        preview: catalog.preview,
+        active,
+    });
+}
+function sameLease(left, right) {
+    return left?.token === right?.token;
+}
+function assertSessionWorkspace(meta, id, workspaceRoot, workspaceDigest) {
+    if (meta.id !== id || meta.workspaceDigest !== workspaceDigest ||
+        workspaceKey(meta.workspaceRoot) !== workspaceKey(workspaceRoot))
+        throw new Error("session belongs to a different workspace");
+}
 function assertSharedNodes(previous, next, replacedId) {
     for (const node of previous.nodes) {
         if (node.id === replacedId)
@@ -301,6 +380,7 @@ function assertSharedNodes(previous, next, replacedId) {
 function assertSnapshot(snapshot, workspaceRoot, workspaceDigest) {
     encodeMeta(snapshot.meta);
     encodeHead(snapshot.head);
+    encodeSessionCatalog(snapshot.catalog);
     assertSessionId(snapshot.meta.id);
     if (snapshot.meta.workspaceDigest !== workspaceDigest ||
         workspaceKey(snapshot.meta.workspaceRoot) !== workspaceKey(workspaceRoot))
@@ -312,14 +392,9 @@ function assertSnapshot(snapshot, workspaceRoot, workspaceDigest) {
         active.revision !== snapshot.head.revision ||
         snapshot.head.sequence < snapshot.conversation.nodes.length)
         throw new Error("session snapshot does not match its verified head");
-}
-function sameHead(left, right) {
-    return left.version === right.version &&
-        left.sequence === right.sequence &&
-        left.nodeId === right.nodeId &&
-        left.parentId === right.parentId &&
-        left.revision === right.revision &&
-        left.updatedAt === right.updatedAt;
+    if (!catalogMatches(snapshot.catalog, snapshot.meta, snapshot.head)) {
+        throw new Error("session snapshot does not match its verified catalogue");
+    }
 }
 async function assertMissingNode(file) {
     try {
@@ -393,17 +468,6 @@ async function makePrivateDirectory(directory) {
     if (process.platform !== "win32")
         await chmod(directory, DIRECTORY_MODE);
 }
-async function directoryEntries(directory) {
-    try {
-        await assertDirectory(directory);
-        return await readdir(directory, { withFileTypes: true });
-    }
-    catch (error) {
-        if (error.code === "ENOENT")
-            return [];
-        throw error;
-    }
-}
 async function removeTemporaryDirectory(directory, bucket) {
     const relative = path.relative(bucket, directory);
     if (relative === "" || relative.startsWith("..") || path.isAbsolute(relative) ||
@@ -411,26 +475,6 @@ async function removeTemporaryDirectory(directory, bucket) {
         throw new Error("refusing to remove an unverified session directory");
     await rm(directory, { recursive: true, force: true });
 }
-function selectedTurnCount(conversation) {
-    let count = 0;
-    let id = conversation.activeNodeId;
-    while (id !== 0) {
-        count++;
-        id = conversation.node(id)?.parentId ?? 0;
-    }
-    return count;
-}
-function firstUserText(conversation) {
-    for (const message of conversation.history) {
-        if (message.role !== "user")
-            continue;
-        const text = message.content.find((block) => block.kind === "text")?.text
-            .replace(/\s+/gu, " ").trim();
-        if (text !== undefined && text !== "")
-            return leadingText(text, 160);
-    }
-    return "Untitled session";
-}
 function nodeName(id) {
     return `${String(id).padStart(6, "0")}.json`;
 }

package/dist/tools/search.js

@@ -232,11 +232,10 @@ function preferRipgrep(files, bytes) {
     return files.length >= MIN_RG_TAIL_FILES || bytes >= MIN_RG_TAIL_BYTES;
 }
 async function walk(start, ctx, visit) {
-    const pending = [start];
+    const pending = [];
     let seen = 0;
-    while (pending.length > 0) {
+    const enter = async (lexical) => {
         checkAbort(ctx.signal);
-        const lexical = pending.pop();
         const directory = await resolveExistingInRoot(ctx.root, lexical);
         let entries;
         try {
@@ -244,24 +243,34 @@ async function walk(start, ctx, visit) {
         }
         catch (error) {
             if (skippable(error))
-                continue;
+                return;
             throw error;
         }
         entries.sort((a, b) => a.name.localeCompare(b.name));
-        for (const entry of entries) {
-            checkAbort(ctx.signal);
-            if (++seen > MAX_VISITED)
-                return { capped: true };
-            if (entry.isSymbolicLink())
-                continue;
-            const target = path.join(directory, entry.name);
-            if (entry.isDirectory()) {
-                if (!SKIP.has(entry.name))
-                    pending.push(target);
-            }
-            else if (entry.isFile() && (await visit(target))) {
-                return { capped: false };
-            }
+        pending.push({ directory, entries, next: 0 });
+    };
+    await enter(start);
+    while (pending.length > 0) {
+        checkAbort(ctx.signal);
+        const frame = pending[pending.length - 1];
+        if (frame === undefined)
+            break;
+        const entry = frame.entries[frame.next++];
+        if (entry === undefined) {
+            pending.pop();
+            continue;
+        }
+        if (++seen > MAX_VISITED)
+            return { capped: true };
+        if (entry.isSymbolicLink())
+            continue;
+        const target = path.join(frame.directory, entry.name);
+        if (entry.isDirectory()) {
+            if (!SKIP.has(entry.name))
+                await enter(target);
+        }
+        else if (entry.isFile() && (await visit(target))) {
+            return { capped: false };
         }
     }
     return { capped: false };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@giovannijecha/jecode",
-  "version": "0.8.3",
+  "version": "0.8.4",
   "description": "An owned coding agent with zero external runtime dependencies.",
   "license": "MIT",
   "repository": {
@@ -26,6 +26,7 @@
     "bin/",
     "dist/",
     "assets/jeco-256.png",
+    "assets/wordmark-steel.svg",
     "LICENSE",
     "README.md"
   ],