@giovannijecha/jecode 0.4.0 → 0.5.0

package/README.md

@@ -25,7 +25,7 @@
   <a href="https://github.com/giovannijecha/jecode/releases">Releases</a>
 </p>
 
-> Jecode is an early 0.4.x release. The core loop is usable today; commands and
+> Jecode is an early 0.5.x release. The core loop is usable today; commands and
 > terminal interactions may still evolve before 1.0.
 
 ## Why Jecode
@@ -37,6 +37,8 @@
   diffs, approvals, reasoning, and status all share one full-screen TUI.
 - **Permission-aware.** Reads stay transparent; dangerous actions ask first.
   Session approvals can be reviewed and revoked.
+- **Durable by default.** Interactive conversations survive terminal exits and
+  can be resumed without replaying tools. Batch runs remain stateless.
 - **Provider-neutral.** Use Anthropic or OpenAI API keys, a ChatGPT account, or
   a local/remote Ollama server without changing the workflow.
 - **Lean by construction.** Jecode installs as plain JavaScript, runs on
@@ -66,6 +68,16 @@ cd path/to/your/project
 jecode
 ~~~
 
+Resume a saved conversation for the current project with a searchable picker,
+or open the most recent one directly:
+
+~~~console
+jecode resume
+jecode resume --latest
+~~~
+
+Use `jecode --ephemeral` when a conversation must stay memory-only.
+
 You can point at another workspace explicitly:
 
 ~~~console
@@ -186,7 +198,7 @@ Type **/** to open searchable command completion inside the composer.
 | /providers | Manage API keys, ChatGPT sign-in, and Ollama connections |
 | /models | Search models across every available provider and select one |
 | /permissions | Change session tool access inline and review remembered approvals |
-| /new | Start a clean conversation and reset session tool permissions |
+| /new | Close the current conversation, start clean, and reset tool permissions |
 | /export | Save a timestamped Markdown transcript in the launch directory |
 | /help | Open a temporary keyboard reference in the composer dock |
 | /exit | Restore the terminal and exit |
@@ -206,12 +218,12 @@ Useful controls:
   the place you are reading.
 - **Ctrl+O** expands or compacts the latest reasoning or tool-detail block.
 
-The one-line footer keeps model, effort, and workspace on the left. Live work
-stays visible on the reasoning and tool rail; the right edge carries the
-interrupt hint, readiness guidance, and temporary feedback without polluting
-the transcript. Slash commands never append content to the conversation or its
-Markdown export; **/help** closes with **Esc**, and token accounting remains
-internal to the active session.
+The one-line footer keeps model, effort, and workspace on the left. While work
+is active, the right edge shows its current state, elapsed time, and interrupt
+hint; readiness guidance and temporary feedback use the same replaceable space
+without polluting the transcript. Slash commands never append content to the
+conversation or its Markdown export; **/help** closes with **Esc**, and token
+accounting remains internal to the active session.
 
 ## Configuration
 
@@ -229,6 +241,7 @@ settings, built-in defaults.
 | --max-steps | JECODE_MAX_STEPS | 40 |
 | --reduced-motion | JECODE_REDUCED_MOTION=1 | Off |
 | --auto-approve | JECODE_AUTO_APPROVE=1 | Off |
+| --ephemeral | JECODE_EPHEMERAL=1 | Off |
 
 Persistent preferences live in **~/.jecode/settings.json**. Explicitly saved
 API keys live in **~/.jecode/credentials.json**; the ChatGPT OAuth account lives
@@ -238,6 +251,21 @@ always win. Model selection saves the provider and model as one change; the
 separate startup flags remain available for automation and override that saved
 choice.
 
+Interactive conversations are stored under **~/.jecode/sessions**, scoped to
+the canonical workspace path. A checkpoint contains normalized messages and
+the settled transcript needed to redraw the conversation. It excludes stored
+provider credentials, OAuth tokens, provider-only opaque response data,
+permission choices, draft composer text, transient footer notices, and pending
+tool state. Session
+files use owner-only modes on POSIX; Windows relies on the user-profile ACL.
+`jecode resume` keeps the same durable session identity and advances that
+session's conversation tree, so reopening and continuing a conversation does
+not create duplicate picker entries. `/new` or a fresh launch starts another
+logical session. Resume never executes an old tool call. If a crash left the
+newest turn inside a tool loop, the same session resumes from its latest
+completed ancestor and the next turn becomes a branch inside its tree because
+provider-only continuation data is intentionally not stored.
+
 Jecode has one interface theme: dark Steel. **NO_COLOR** is supported for
 terminals and pipelines that disable colour.
 
@@ -249,6 +277,8 @@ When stdin or stdout is piped, Jecode switches to a plain line-oriented mode:
 printf "explain this project\n" | jecode --root .
 ~~~
 
+Batch conversations are never written to the session store.
+
 Dangerous tools stay denied in batch mode unless **--auto-approve** is supplied
 explicitly. A terminal batch failure is written to stderr and exits non-zero,
 so shell pipelines can stop reliably.
@@ -277,6 +307,9 @@ untrusted data.
   idempotent catalogue reads retry; generation requests are never replayed.
 - Model and filesystem input are bounded before they reach the screen or
   provider.
+- Durable session files are versioned, size-bounded, atomically checkpointed,
+  and treated as untrusted when loaded. A live lease prevents the same saved
+  session from being resumed by two Jecode processes at once.
 
 `run_command` is not an operating-system sandbox: an approved shell command can
 still access files and account resources available to the current user. Review

package/dist/batch.js

@@ -30,9 +30,29 @@ export async function runBatch(session, environment = {}) {
                 continue;
             }
             write(`> ${terminalText(line)}\n`);
-            session.history.push({ role: "user", content: [{ kind: "text", text: line }] });
+            const parentId = session.conversation.activeNodeId;
+            const createdAt = new Date().toISOString();
+            const history = session.conversation.history;
+            const before = history.length;
+            let nodeId;
+            history.push({ role: "user", content: [{ kind: "text", text: line }] });
             const turn = events(emit, session);
-            await runTurn(session.history, options(session), turn);
+            turn.onCheckpoint = async (checkpoint, settlement) => {
+                session.conversation = session.conversation.commit({
+                    ...(nodeId === undefined ? {} : { nodeId }),
+                    parentId,
+                    createdAt,
+                    identity: {
+                        providerId: session.provider.id,
+                        model: session.model,
+                        effort: session.config.effort,
+                    },
+                    messages: checkpoint.slice(before),
+                    blocks: [],
+                }, settlement);
+                nodeId = session.conversation.activeNodeId;
+            };
+            await runTurn(history, options(session), turn);
             turn.flush();
         }
     }

package/dist/cli-info.js

@@ -5,6 +5,7 @@ const HELP = `jecode — an owned coding agent for the terminal
 
 Usage:
   jecode [options]
+  jecode resume [--latest] [options]
 
 Options:
   --root <path>          workspace root (default: current directory)
@@ -16,6 +17,8 @@ Options:
   --max-steps <number>   tool-loop ceiling
   --reduced-motion       disable animated terminal states
   --auto-approve         allow dangerous tools for this process
+  --ephemeral            do not save this conversation
+  --latest               resume the newest session without a picker
   -h, --help             show this help
   -v, --version          show the installed version
 

package/dist/commands.js

@@ -4,6 +4,7 @@
 // without asking the provider what it has — but none of them ever sends a
 // message. Provider access and model selection stay in their own commands;
 // this file keeps discovery, dispatch, and local session operations.
+import { ConversationTree } from "./conversation.js";
 import { modelsCommand } from "./model-command.js";
 import { providersCommand } from "./provider-commands.js";
 import { permissionsCommand } from "./permission-command.js";
@@ -45,9 +46,9 @@ export async function handleCommand(line, session, host) {
         case "exit":
             return "exit";
         case "new":
-            session.history.length = 0;
+            await host.reset?.();
+            session.conversation = ConversationTree.empty();
             session.usage = emptyUsage();
-            host.reset?.();
             host.emit({ kind: "notice", text: "new session", tone: "info" });
             return "handled";
         case "export":

package/dist/config.js

@@ -12,6 +12,7 @@ const FLAGS = [
     "max-steps",
     "root",
     "auto-approve",
+    "ephemeral",
 ];
 export function loadConfig(argv, saved = readSettings()) {
     const flags = parseFlags(argv);
@@ -42,6 +43,7 @@ export function loadConfig(argv, saved = readSettings()) {
         maxSteps: toInt(pick(flags["max-steps"], process.env.JECODE_MAX_STEPS, String(saved.maxSteps ?? 40)), "max-steps"),
         root: path.resolve(pick(flags.root, undefined, process.cwd())),
         autoApprove: flags["auto-approve"] === "true" || process.env.JECODE_AUTO_APPROVE === "1",
+        ephemeral: bool(flags.ephemeral, process.env.JECODE_EPHEMERAL, false),
     };
 }
 function bool(flag, env, fallback) {

package/dist/controller.js

@@ -44,6 +44,7 @@ export async function runTurn(history, options, events, signal) {
         if (calls.length === 0) {
             if (assistant.usage !== undefined)
                 events.onUsage?.(assistant.usage);
+            await events.onCheckpoint?.(history, "completed");
             return; // the model is done — hand back to the user
         }
         // Consecutive shared reads run together. An exclusive call is an ordered
@@ -100,11 +101,13 @@ export async function runTurn(history, options, events, signal) {
                     // The surface is already failing; the next turn can still proceed.
                 }
             }
+            await events.onCheckpoint?.(history, "checkpointed");
             if (interrupted)
                 throw abortReason(signal);
             throw error;
         }
         history.push({ role: "user", content: results });
+        await events.onCheckpoint?.(history, "checkpointed");
     }
     throw new Error(`gave up after ${options.maxSteps} steps without finishing (raise --max-steps)`);
 }

package/dist/conversation.js

@@ -0,0 +1,208 @@
+// Canonical settled conversation state.
+//
+// A node owns one complete user-turn delta. The selected root-to-node path is
+// the only history sent to a provider and the only transcript shown by the
+// TUI. Provider traffic and live screen blocks remain prospective until the
+// controller reaches a consistent completion or tool checkpoint.
+export const CONVERSATION_LIMITS = Object.freeze({
+    nodes: 1_024,
+    messageCodeUnits: 8_388_608,
+    transcriptCodeUnits: 8_388_608,
+});
+/** Immutable tree with one selected model/transcript path. */
+export class ConversationTree {
+    #nodes;
+    #activeNodeId;
+    constructor(nodes, activeNodeId) {
+        this.#nodes = Object.freeze([...nodes]);
+        this.#activeNodeId = activeNodeId;
+        Object.freeze(this);
+    }
+    static empty() {
+        return new ConversationTree([], 0);
+    }
+    static restore(nodes, activeNodeId) {
+        let tree = ConversationTree.empty();
+        for (let index = 0; index < nodes.length; index++) {
+            const node = nodes[index];
+            if (node === undefined || node.id !== index + 1) {
+                throw new Error("session contains a non-sequential conversation node");
+            }
+            tree = tree.select(node.parentId).commit({
+                parentId: node.parentId,
+                createdAt: node.createdAt,
+                identity: node.identity,
+                messages: node.messages,
+                blocks: node.blocks,
+            }, node.settlement);
+            const restored = tree.activeNode;
+            if (restored === undefined || restored.id !== node.id) {
+                throw new Error("session conversation could not be restored");
+            }
+            if (node.revision > 1) {
+                const copy = [...tree.#nodes];
+                copy[node.id - 1] = ownedNode({ ...restored, revision: node.revision });
+                tree = new ConversationTree(copy, node.id);
+            }
+        }
+        return tree.select(activeNodeId);
+    }
+    /** Commit or extend the one prospective leaf turn. */
+    commit(draft, settlement) {
+        if (draft.parentId !== (draft.nodeId === undefined
+            ? this.#activeNodeId
+            : this.node(draft.nodeId)?.parentId)) {
+            throw new Error("turn parent no longer matches the selected conversation");
+        }
+        if (draft.nodeId === undefined)
+            return this.#append(draft, settlement);
+        return this.#replace(draft, settlement);
+    }
+    select(nodeId) {
+        if (!validNodeId(nodeId) || (nodeId !== 0 && this.#nodes[nodeId - 1]?.id !== nodeId)) {
+            throw new Error("conversation node does not exist");
+        }
+        return new ConversationTree(this.#nodes, nodeId);
+    }
+    node(nodeId) {
+        return nodeId === 0 ? undefined : this.#nodes[nodeId - 1];
+    }
+    get nodes() {
+        return this.#nodes;
+    }
+    get activeNodeId() {
+        return this.#activeNodeId;
+    }
+    get activeNode() {
+        return this.node(this.#activeNodeId);
+    }
+    /** Select the newest completed turn on the active path, if one exists. */
+    latestCompleted() {
+        let id = this.#activeNodeId;
+        while (id !== 0) {
+            const node = this.node(id);
+            if (node === undefined)
+                throw new Error("conversation path is incomplete");
+            if (node.settlement === "completed")
+                return this.select(id);
+            id = node.parentId;
+        }
+        return undefined;
+    }
+    get history() {
+        return this.#path().flatMap((node) => clone(node.messages));
+    }
+    get transcript() {
+        return this.#path().flatMap((node) => clone(node.blocks));
+    }
+    #append(draft, settlement) {
+        if (this.#nodes.length >= CONVERSATION_LIMITS.nodes) {
+            throw new Error("conversation reached its session limit — start /new");
+        }
+        const node = ownedNode({
+            id: this.#nodes.length + 1,
+            parentId: draft.parentId,
+            revision: 1,
+            createdAt: draft.createdAt,
+            settlement,
+            identity: draft.identity,
+            messages: draft.messages,
+            blocks: settledBlocks(draft.blocks),
+        });
+        assertTurn(node);
+        const nodes = [...this.#nodes, node];
+        assertBounds(nodes);
+        return new ConversationTree(nodes, node.id);
+    }
+    #replace(draft, settlement) {
+        const id = draft.nodeId;
+        const current = this.node(id);
+        if (current === undefined || id !== this.#activeNodeId || this.#nodes.some((node) => node.parentId === id)) {
+            throw new Error("only the active leaf turn can be checkpointed");
+        }
+        const node = ownedNode({
+            ...current,
+            revision: current.revision + 1,
+            settlement,
+            identity: draft.identity,
+            messages: draft.messages,
+            blocks: settledBlocks(draft.blocks),
+        });
+        assertTurn(node);
+        const nodes = [...this.#nodes];
+        nodes[id - 1] = node;
+        assertBounds(nodes);
+        return new ConversationTree(nodes, id);
+    }
+    #path() {
+        const path = [];
+        let id = this.#activeNodeId;
+        while (id !== 0) {
+            const node = this.node(id);
+            if (node === undefined)
+                throw new Error("conversation path is incomplete");
+            path.push(node);
+            id = node.parentId;
+        }
+        path.reverse();
+        return path;
+    }
+}
+function ownedNode(node) {
+    return Object.freeze({
+        ...node,
+        identity: Object.freeze({ ...node.identity }),
+        messages: Object.freeze(clone(node.messages)),
+        blocks: Object.freeze(clone(node.blocks)),
+    });
+}
+function settledBlocks(blocks) {
+    return clone(blocks).flatMap((block) => {
+        if (block.kind === "notice")
+            return [];
+        if (block.kind === "reasoning") {
+            const { live: _live, expanded: _expanded, ...settled } = block;
+            return [settled];
+        }
+        if (block.kind === "tool") {
+            const { startedAt: _startedAt, expanded: _expanded, ...settled } = block;
+            return [settled];
+        }
+        return [block];
+    });
+}
+function assertTurn(node) {
+    if (!validNodeId(node.id) || node.id === 0 ||
+        !validNodeId(node.parentId) || node.parentId >= node.id ||
+        !Number.isSafeInteger(node.revision) || node.revision < 1 ||
+        node.createdAt.length === 0 || node.createdAt.length > 64 ||
+        (node.settlement !== "checkpointed" && node.settlement !== "completed") ||
+        node.messages.length < 2 || node.messages[0]?.role !== "user" ||
+        node.identity.providerId.length === 0 || node.identity.providerId.length > 128 ||
+        node.identity.model.length === 0 || node.identity.model.length > 512 ||
+        node.identity.effort.length === 0 || node.identity.effort.length > 32)
+        throw new Error("turn checkpoint is invalid");
+    if (node.settlement === "completed" && node.messages.at(-1)?.role !== "assistant") {
+        throw new Error("a completed turn must end with an assistant message");
+    }
+}
+function assertBounds(nodes) {
+    let messageCodeUnits = 0;
+    let transcriptCodeUnits = 0;
+    for (const node of nodes) {
+        messageCodeUnits += JSON.stringify(node.messages).length;
+        transcriptCodeUnits += JSON.stringify(node.blocks).length;
+    }
+    if (messageCodeUnits > CONVERSATION_LIMITS.messageCodeUnits) {
+        throw new Error("conversation model history reached its session limit — start /new");
+    }
+    if (transcriptCodeUnits > CONVERSATION_LIMITS.transcriptCodeUnits) {
+        throw new Error("conversation transcript reached its session limit — start /new");
+    }
+}
+function validNodeId(value) {
+    return Number.isSafeInteger(value) && value >= 0;
+}
+function clone(value) {
+    return structuredClone(value);
+}

package/dist/launch.js

@@ -0,0 +1,19 @@
+export function parseLaunch(argv) {
+    const first = argv[0];
+    if (first !== undefined && !first.startsWith("--") && first !== "-h" && first !== "-v") {
+        if (first !== "resume")
+            throw new Error(`unknown command ${first}`);
+        const rest = argv.slice(1);
+        const latest = rest.filter((value) => value === "--latest").length;
+        if (latest > 1)
+            throw new Error("--latest may be passed only once");
+        return {
+            kind: "resume",
+            latest: latest === 1,
+            configArgs: rest.filter((value) => value !== "--latest"),
+        };
+    }
+    if (argv.includes("--latest"))
+        throw new Error("--latest requires `jecode resume`");
+    return { kind: "new", latest: false, configArgs: [...argv] };
+}

package/dist/providers/ollama.js

@@ -5,6 +5,7 @@
 // daemon. There is no default model — the catalogue is whatever the host has
 // pulled or the subscription grants — so the model has to be named with
 // --model.
+import { requireSupportedEffort } from "../effort.js";
 import { postSse } from "./http.js";
 import { listModels } from "./catalog.js";
 import { keyFor } from "../credentials.js";
@@ -12,6 +13,8 @@ import { assembleOllama } from "./ollama-stream.js";
 import { OLLAMA_CLOUD_HOST, OLLAMA_LOCAL_HOST, ollamaConnectionKind, parseOllamaEndpoint, } from "./ollama-endpoint.js";
 import { fromWireReply, stopNotice, toWireMessages, toWireTool } from "./ollama-wire.js";
 const KEY = "OLLAMA_API_KEY";
+// Ollama also accepts `none`; Jecode's product-wide reasoning floor is `low`.
+const OLLAMA_EFFORTS = ["low", "medium", "high"];
 let configuredHost;
 /** Set the endpoint selected for this process. Undefined restores key-aware inference. */
 export function configureOllama(host) {
@@ -46,7 +49,7 @@ export const ollama = {
         return listModels(`${at.baseUrl}/v1/models`, headers(at), signal, onStatus);
     },
     async efforts() {
-        return [];
+        return OLLAMA_EFFORTS;
     },
     location: () => {
         try {
@@ -58,13 +61,15 @@ export const ollama = {
     },
     async send(req) {
         const at = endpoint();
-        // `effort` has no equivalent in this shape and is dropped rather than
-        // guessed at — depth on these models is a property of the model chosen.
+        const effort = requireSupportedEffort(req.model, req.effort, OLLAMA_EFFORTS);
+        // The OpenAI-compatible endpoint accepts this vocabulary for thinking
+        // models. Invalid levels are rejected locally instead of being rewritten.
         const events = await postSse(`${at.baseUrl}/v1/chat/completions`, headers(at), {
             model: req.model,
             messages: toWireMessages(req.system, req.messages),
             tools: req.tools.map(toWireTool),
             max_tokens: req.maxTokens,
+            reasoning_effort: effort,
             stream: true,
         }, req.signal, req.onStatus);
         const reply = await assembleOllama(events, req.onStream);