@giovannijecha/jecode 0.3.2 → 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.3.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
@@ -146,10 +158,11 @@ published package runs no compilation or installation scripts.
 ## First session
 
 Jecode opens on an empty composer instead of forcing a setup wizard. Type
-**/settings** when you are ready to choose a provider, select a model, and
-configure authentication. An API key can remain in memory for the current
-session or be saved explicitly under **~/.jecode**; it is never stored in the
-workspace.
+**/providers** to connect the services you use, then **/models** to choose from
+their combined live catalogues. **/settings** keeps the selected model and the
+remaining non-secret defaults together. An API key can remain in memory for
+the current session or be saved explicitly under **~/.jecode**; it is never
+stored in the workspace.
 
 | Provider ID | Authentication | Notes |
 |---|---|---|
@@ -158,7 +171,8 @@ workspace.
 | openai-codex | ChatGPT OAuth | Experimental; uses eligible ChatGPT Codex access |
 | ollama | OLLAMA_API_KEY for Cloud/remote | Cloud with a key, local without one |
 
-Choose **openai-codex** to sign in on OpenAI's website without pasting a key.
+Choose **ChatGPT** in **/providers** to sign in on OpenAI's website without
+pasting a key.
 Jecode offers a local browser callback and a device-code flow; WSL and remote
 terminals default to the device code. The connection is saved only after the
 flow completes. Availability and usage limits are determined by the ChatGPT
@@ -168,10 +182,10 @@ and is not an endorsement of Jecode by OpenAI.
 Anthropic remains API-key only. Jecode does not reuse a Claude consumer
 subscription or copy credentials from another client.
 
-Choose **cloud**, **local**, or a custom endpoint from the Ollama connection row
-in **/settings**. Existing users with an Ollama API key automatically use
-**https://ollama.com**; without a key, Jecode uses the local daemon at
-**http://127.0.0.1:11434**. Remote custom endpoints must use HTTPS.
+Choose **Ollama** in **/providers** to manage its API key and select **cloud**,
+**local**, or a custom endpoint. Existing users with an Ollama API key
+automatically use **https://ollama.com**; without a key, Jecode uses the local
+daemon at **http://127.0.0.1:11434**. Remote custom endpoints must use HTTPS.
 
 ## Use the TUI
 
@@ -179,13 +193,12 @@ Type **/** to open searchable command completion inside the composer.
 
 | Command | What it does |
 |---|---|
-| /settings | Manage provider, connection, model, limits, motion, and authentication |
+| /settings | Manage the selected model, limits, effort, motion, and provider access |
 | /effort | Change and save reasoning effort directly |
-| /providers | Switch the provider for the next turn |
-| /models | Search the live model catalogue |
-| /credentials | Manage API keys and the connected ChatGPT account |
-| /permissions | Manage session tool access and remembered approvals |
-| /new | Start a clean conversation and reset session tool permissions |
+| /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 | 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 |
@@ -193,6 +206,10 @@ Type **/** to open searchable command completion inside the composer.
 Useful controls:
 
 - **Up/Down** moves through command suggestions, menus, and input history.
+- **Left/Right** moves the composer cursor or changes an inline menu value;
+  **Ctrl+Left/Right** moves by word.
+- **Backspace/Delete** removes one character; **Ctrl+Backspace/Delete** removes
+  one word. **Home/End** moves to the start or end of the composer.
 - **Tab** completes a slash command without running it; **Enter** sends.
 - **Alt+Enter** inserts a newline.
 - **Esc** closes a menu or interrupts the foreground operation.
@@ -201,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
 
@@ -224,12 +241,30 @@ 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
 separately in **~/.jecode/accounts.json**. Both secret stores use owner-only
 permissions where the operating system supports them. Environment API keys
-always win.
+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.
@@ -242,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.
@@ -270,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/command-settings.js

@@ -0,0 +1,19 @@
+// Shared persistence boundary for commands that change non-secret defaults.
+import { updateSettings } from "./settings.js";
+export async function saveCommandSettings(host, patch) {
+    try {
+        if (host.saveSettings === undefined)
+            await updateSettings(patch);
+        else
+            await host.saveSettings(patch);
+        return true;
+    }
+    catch (error) {
+        host.emit({
+            kind: "notice",
+            text: `could not save settings · ${error.message}`,
+            tone: "error",
+        });
+        return false;
+    }
+}

package/dist/commands.js

@@ -2,10 +2,11 @@
 //
 // One of them does reach the network — a menu of models cannot be built
 // without asking the provider what it has — but none of them ever sends a
-// message. Provider and credential interaction lives in provider-commands.ts;
-// this file keeps command discovery, dispatch, and local session operations.
-import { modelsCommand, providersCommand } from "./provider-commands.js";
-import { credentialsCommand } from "./credential-commands.js";
+// 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";
 import { effortCommand, settingsCommand } from "./settings-command.js";
 import { emptyUsage } from "./usage.js";
@@ -13,8 +14,8 @@ import { emptyUsage } from "./usage.js";
  * The commands, declared once.
  *
  * Deliberately short. `/settings` owns persistent defaults; the narrower
- * provider, model, effort, and credential commands remain useful direct paths
- * into the same interactions.
+ * model, provider-access, and effort commands remain useful direct paths into
+ * the same interactions.
  */
 export const COMMANDS = [
     { name: "help", blurb: "show keyboard controls" },
@@ -24,9 +25,8 @@ export const COMMANDS = [
     { name: "permissions", blurb: "manage session tool access" },
     { name: "settings", blurb: "change and save jecode defaults" },
     { name: "effort", blurb: "set the reasoning effort" },
-    { name: "credentials", blurb: "manage API keys and connected accounts" },
-    { name: "models", blurb: "pick a model, from what the provider offers" },
-    { name: "providers", blurb: "pick a provider" },
+    { name: "models", blurb: "choose from every available provider" },
+    { name: "providers", blurb: "manage provider access and connections" },
 ];
 export async function handleCommand(line, session, host) {
     const [name] = line.slice(1).trim().split(/\s+/);
@@ -46,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":
@@ -69,9 +69,6 @@ export async function handleCommand(line, session, host) {
         case "effort":
             await effortCommand(session, host);
             return "handled";
-        case "credentials":
-            await credentialsCommand(session, host);
-            return "handled";
         case "models":
             await modelsCommand(session, host);
             return "handled";

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);
+}