@giovannijecha/jecode 0.6.0 → 0.7.1

package/dist/commands.js

@@ -1,9 +1,8 @@
 // Slash-command registry and dispatcher.
 //
-// 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 access and model selection stay in their own commands;
-// this file keeps discovery, dispatch, and local session operations.
+// Model discovery and explicit context compaction can reach a provider, but
+// slash commands never become user messages. This file keeps discovery,
+// dispatch, and session operations outside the canonical transcript.
 import { ConversationTree } from "./conversation.js";
 import { modelsCommand } from "./model-command.js";
 import { providersCommand } from "./provider-commands.js";
@@ -22,6 +21,8 @@ export const COMMANDS = [
     { name: "exit", blurb: "exit and restore the terminal" },
     { name: "new", blurb: "start clean and reset tool permissions" },
     { name: "export", blurb: "save this transcript as Markdown" },
+    { name: "timeline", blurb: "navigate this conversation tree" },
+    { name: "compact", blurb: "compact the active context now" },
     { name: "permissions", blurb: "manage session tool access" },
     { name: "settings", blurb: "change and save jecode defaults" },
     { name: "effort", blurb: "set the reasoning effort" },
@@ -51,6 +52,39 @@ export async function handleCommand(line, session, host) {
             session.usage = emptyUsage();
             host.emit({ kind: "notice", text: "new session", tone: "info" });
             return "handled";
+        case "timeline": {
+            if (host.timeline === undefined) {
+                host.emit({ kind: "notice", text: "timeline needs the interactive screen", tone: "warn" });
+                return "handled";
+            }
+            const result = await host.timeline();
+            if (result === "selected") {
+                host.emit({
+                    kind: "notice",
+                    text: "branch point selected · send a message to continue",
+                    tone: "info",
+                });
+            }
+            return "handled";
+        }
+        case "compact": {
+            if (host.compact === undefined) {
+                host.emit({ kind: "notice", text: "compact is unavailable here", tone: "warn" });
+                return "handled";
+            }
+            const result = await host.compact();
+            if (result === "compacted") {
+                host.emit({ kind: "notice", text: "context compacted", tone: "info" });
+            }
+            else if (result === "branch-pending") {
+                host.emit({
+                    kind: "notice",
+                    text: "send a message on this branch before compacting",
+                    tone: "warn",
+                });
+            }
+            return "handled";
+        }
         case "export":
             if (host.exportTranscript === undefined) {
                 host.emit({ kind: "notice", text: "export needs the interactive screen", tone: "warn" });
@@ -84,9 +118,3 @@ export async function handleCommand(line, session, host) {
             return "handled";
     }
 }
-function chooser(host) {
-    if (host.choose === undefined) {
-        host.emit({ kind: "notice", text: "that command needs the screen", tone: "warn" });
-    }
-    return host.choose;
-}

package/dist/config.js

@@ -3,29 +3,24 @@ import * as path from "node:path";
 import { DEFAULT_COMPACTION_PERCENT, MAX_COMPACTION_PERCENT, MIN_COMPACTION_PERCENT, } from "./context/policy.js";
 import { EFFORTS, readSettings } from "./settings.js";
 import { parseOllamaEndpoint } from "./providers/ollama-endpoint.js";
-const FLAGS = [
+const VALUE_FLAGS = [
     "provider",
     "model",
     "ollama-host",
-    "reduced-motion",
     "effort",
     "max-tokens",
     "max-steps",
     "compaction-percent",
     "root",
+];
+const BOOLEAN_FLAGS = [
+    "reduced-motion",
     "auto-approve",
     "ephemeral",
 ];
+const FLAGS = [...VALUE_FLAGS, ...BOOLEAN_FLAGS];
 export function loadConfig(argv, saved = readSettings()) {
     const flags = parseFlags(argv);
-    // A flag nobody declared is a typo. Swallowed in silence it becomes a
-    // setting the user believes is on, and the run that ignores it looks like
-    // the feature is broken rather than misspelled.
-    for (const name of Object.keys(flags)) {
-        if (!FLAGS.includes(name)) {
-            throw new Error(`unknown flag --${name} (known: ${FLAGS.map((f) => `--${f}`).join(", ")})`);
-        }
-    }
     const providerId = pick(flags.provider, process.env.JECODE_PROVIDER, saved.provider ?? "anthropic");
     const ollamaHost = optional(flags["ollama-host"], process.env.OLLAMA_HOST, saved.ollamaHost);
     const effort = pick(flags.effort, process.env.JECODE_EFFORT, saved.effort ?? "high");
@@ -45,7 +40,9 @@ export function loadConfig(argv, saved = readSettings()) {
         maxSteps: toInt(pick(flags["max-steps"], process.env.JECODE_MAX_STEPS, String(saved.maxSteps ?? 40)), "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" || process.env.JECODE_AUTO_APPROVE === "1",
+        autoApprove: flags["auto-approve"] === "true" ||
+            flags["auto-approve"] === "1" ||
+            process.env.JECODE_AUTO_APPROVE === "1",
         ephemeral: bool(flags.ephemeral, process.env.JECODE_EPHEMERAL, false),
     };
 }
@@ -85,27 +82,55 @@ function toPercent(value) {
     }
     return percent;
 }
-// Accepts --key value, --key=value, and bare --flag (which reads as "true").
+// Value flags accept --key value and --key=value. Boolean flags are bare or
+// take a real boolean value, so an accidental positional argument is never
+// swallowed as configuration.
 function parseFlags(argv) {
     const flags = {};
     for (let i = 0; i < argv.length; i++) {
         const arg = argv[i];
-        if (arg === undefined || !arg.startsWith("--"))
+        if (arg === undefined)
             continue;
+        if (!arg.startsWith("--"))
+            throw new Error(`unexpected argument "${arg}"`);
         const body = arg.slice(2);
         const eq = body.indexOf("=");
-        if (eq !== -1) {
-            flags[body.slice(0, eq)] = body.slice(eq + 1);
+        const name = eq === -1 ? body : body.slice(0, eq);
+        const inline = eq === -1 ? undefined : body.slice(eq + 1);
+        if (!FLAGS.includes(name)) {
+            throw new Error(`unknown flag --${name} (known: ${FLAGS.map((flag) => `--${flag}`).join(", ")})`);
+        }
+        if (BOOLEAN_FLAGS.includes(name)) {
+            if (inline === undefined) {
+                const next = argv[i + 1];
+                if (next !== undefined && ["true", "false", "1", "0"].includes(next)) {
+                    flags[name] = next;
+                    i++;
+                }
+                else {
+                    flags[name] = "true";
+                }
+            }
+            else if (["true", "false", "1", "0"].includes(inline)) {
+                flags[name] = inline;
+            }
+            else {
+                throw new Error(`--${name} must be true or false`);
+            }
             continue;
         }
-        const next = argv[i + 1];
-        if (next !== undefined && !next.startsWith("--")) {
-            flags[body] = next;
-            i++;
+        if (inline !== undefined) {
+            if (inline === "")
+                throw new Error(`--${name} requires a value`);
+            flags[name] = inline;
+            continue;
         }
-        else {
-            flags[body] = "true";
+        const next = argv[i + 1];
+        if (next === undefined || next.startsWith("--")) {
+            throw new Error(`--${name} requires a value`);
         }
+        flags[name] = next;
+        i++;
     }
     return flags;
 }

package/dist/context/compactor.js

@@ -45,7 +45,9 @@ export async function compactContext(options) {
             ...(response.usage === undefined ? {} : { usage: response.usage }),
         };
     }
-    catch {
+    catch (error) {
+        if (options.failLoudly === true)
+            throw error;
         return undefined;
     }
     finally {

package/dist/context/manual.js

@@ -0,0 +1,69 @@
+// Explicit compaction of the selected durable leaf.
+//
+// The canonical messages and transcript remain untouched. Only the active
+// leaf receives a new branch-local context anchor, using the same provider
+// policy and summarizer as automatic compaction.
+import { recordAuxiliaryUsage } from "../usage.js";
+import { resolveContextPolicy } from "./capacity.js";
+import { compactContext } from "./compactor.js";
+import { estimateTokens, planCompaction } from "./policy.js";
+const MIN_PREFIX_TOKENS = 512;
+export async function compactSession(session, options = {}) {
+    const active = session.conversation.activeNode;
+    if (active === undefined)
+        return "unchanged";
+    const context = session.conversation.contextHistory;
+    if (estimateTokens(context) < MIN_PREFIX_TOKENS)
+        return "unchanged";
+    if (session.conversation.nodes.some((node) => node.parentId === active.id)) {
+        throw new Error("continue this branch before compacting");
+    }
+    options.onStatus?.("Checking context");
+    const policy = await resolveContextPolicy({
+        provider: session.provider,
+        model: session.model,
+        compactionPercent: session.config.compactionPercent,
+        signal: options.signal,
+        onStatus: (status) => options.onStatus?.(status),
+    });
+    const coveredMessages = active.context?.throughNodeId === active.id
+        ? active.context.messageCount
+        : 0;
+    const plan = planCompaction(context, active.messages, coveredMessages, session.usage.lastInputTokens, true, policy);
+    if (plan === undefined || estimateTokens(plan.prefix) < MIN_PREFIX_TOKENS) {
+        options.onStatus?.();
+        return "unchanged";
+    }
+    const result = await compactContext({
+        provider: session.provider,
+        model: session.model,
+        effort: session.config.effort,
+        context,
+        turn: active.messages,
+        nodeId: active.id,
+        coveredMessages,
+        lastInputTokens: session.usage.lastInputTokens,
+        signal: options.signal,
+        force: true,
+        failLoudly: true,
+        policy,
+        onBegin: () => options.onStatus?.("Compacting"),
+        onEnd: () => options.onStatus?.(),
+    });
+    if (result === undefined)
+        throw new Error("context could not be compacted");
+    if (result.usage !== undefined)
+        recordAuxiliaryUsage(session.usage, result.usage);
+    const next = session.conversation.commit({
+        nodeId: active.id,
+        parentId: active.parentId,
+        createdAt: active.createdAt,
+        identity: active.identity,
+        messages: active.messages,
+        blocks: active.blocks,
+        context: result.anchor,
+    }, active.settlement);
+    await session.persistence?.checkpoint(next);
+    session.conversation = next;
+    return "compacted";
+}

package/dist/credential-safety.js

@@ -40,17 +40,21 @@ export function credentialRedactor(source = process.env) {
             const ready = [];
             let at = 0;
             while (at < combined.length) {
+                const rest = combined.slice(at);
+                // A complete shorter credential can also be the prefix of a longer
+                // one. Hold that ambiguous suffix until the next chunk proves which
+                // value arrived, otherwise the longer credential leaks its tail.
+                if (rest.length < longest &&
+                    values.some((value) => value.length > rest.length && value.startsWith(rest))) {
+                    pending = rest;
+                    return ready.join("");
+                }
                 const complete = values.find((value) => combined.startsWith(value, at));
                 if (complete !== undefined) {
                     ready.push(REDACTED);
                     at += complete.length;
                     continue;
                 }
-                const rest = combined.slice(at);
-                if (rest.length < longest && values.some((value) => value.startsWith(rest))) {
-                    pending = rest;
-                    return ready.join("");
-                }
                 ready.push(combined[at]);
                 at++;
             }

package/dist/providers/anthropic-wire.js

@@ -1,5 +1,6 @@
 // Translation between the normalized vocabulary and the Anthropic wire shape.
 // Pure functions, no I/O — which is what makes them testable without a key.
+import { wireTokenCount } from "./wire-usage.js";
 export function toWireTool(tool) {
     return { name: tool.name, description: tool.description, input_schema: tool.input };
 }
@@ -70,10 +71,10 @@ function normalizeUsage(data) {
     if (usage === undefined)
         return undefined;
     return {
-        inputTokens: usage.input_tokens ?? 0,
-        outputTokens: usage.output_tokens ?? 0,
-        cachedInputTokens: usage.cache_read_input_tokens ?? 0,
-        cacheWriteInputTokens: usage.cache_creation_input_tokens ?? 0,
+        inputTokens: wireTokenCount(usage.input_tokens),
+        outputTokens: wireTokenCount(usage.output_tokens),
+        cachedInputTokens: wireTokenCount(usage.cache_read_input_tokens),
+        cacheWriteInputTokens: wireTokenCount(usage.cache_creation_input_tokens),
         reasoningTokens: 0,
     };
 }

package/dist/providers/ollama-wire.js

@@ -6,6 +6,7 @@
 // Chat Completions differs on two points that matter here — a tool result is a
 // message of its own with role "tool", not a block inside a user turn, and tool
 // arguments travel as a JSON string rather than an object.
+import { wireTokenCount } from "./wire-usage.js";
 export function toWireTool(tool) {
     return {
         type: "function",
@@ -83,8 +84,8 @@ function normalizeUsage(reply) {
     if (reply.usage === undefined)
         return undefined;
     return {
-        inputTokens: reply.usage.prompt_tokens ?? 0,
-        outputTokens: reply.usage.completion_tokens ?? 0,
+        inputTokens: wireTokenCount(reply.usage.prompt_tokens),
+        outputTokens: wireTokenCount(reply.usage.completion_tokens),
         cachedInputTokens: 0,
         cacheWriteInputTokens: 0,
         reasoningTokens: 0,

package/dist/providers/openai-wire.js

@@ -1,6 +1,7 @@
 // Translation between the normalized vocabulary and the OpenAI Responses wire
 // shape: a flat `input` list where tool calls and their outputs are top-level
 // items keyed by `call_id`, rather than blocks nested inside a message.
+import { wireTokenCount } from "./wire-usage.js";
 export function toWireTool(tool) {
     return {
         type: "function",
@@ -83,11 +84,11 @@ function normalizeUsage(data) {
     if (usage === undefined || usage === null)
         return undefined;
     return {
-        inputTokens: usage.input_tokens ?? 0,
-        outputTokens: usage.output_tokens ?? 0,
-        cachedInputTokens: usage.input_tokens_details?.cached_tokens ?? 0,
-        cacheWriteInputTokens: usage.input_tokens_details?.cache_write_tokens ?? 0,
-        reasoningTokens: usage.output_tokens_details?.reasoning_tokens ?? 0,
+        inputTokens: wireTokenCount(usage.input_tokens),
+        outputTokens: wireTokenCount(usage.output_tokens),
+        cachedInputTokens: wireTokenCount(usage.input_tokens_details?.cached_tokens),
+        cacheWriteInputTokens: wireTokenCount(usage.input_tokens_details?.cache_write_tokens),
+        reasoningTokens: wireTokenCount(usage.output_tokens_details?.reasoning_tokens),
     };
 }
 // Arguments arrive as a JSON string and models vary in how they escape it, so

package/dist/providers/wire-usage.js

@@ -0,0 +1,6 @@
+// Usage comes from remote JSON and eventually reaches the strict session
+// codec. Normalize it at the wire boundary so one malformed counter cannot
+// make an otherwise valid saved session unreadable.
+export function wireTokenCount(value) {
+    return typeof value === "number" && Number.isSafeInteger(value) && value >= 0 ? value : 0;
+}

package/dist/settings-command.js

@@ -202,7 +202,7 @@ async function compactionSetting(session, host) {
     const label = "context compaction";
     const field = {
         title: heading(label, `${MIN_COMPACTION_PERCENT}-${MAX_COMPACTION_PERCENT} percent`, session.palette),
-        right: "enter save · esc back",
+        right: "enter save · esc back",
         editor: of(String(session.config.compactionPercent)),
         secret: false,
         note: "Compacts when model context reaches this percentage.",

package/dist/timeline.js

@@ -0,0 +1,90 @@
+// A compact, read-only projection of the durable conversation tree.
+//
+// Selecting a node changes only the in-memory path. The next real user turn
+// is what persists a branch, so opening or cancelling this control plane can
+// never create empty history.
+import { usageFromHistory } from "./usage.js";
+import { heading } from "./tui/picker.js";
+export function timelinePicker(conversation, palette) {
+    const entries = timelineEntries(conversation);
+    const selectedId = conversation.latestCompleted()?.activeNodeId ?? 0;
+    const index = Math.max(0, entries.findIndex((entry) => entry.node.id === selectedId));
+    return Object.freeze({
+        picker: {
+            title: heading("timeline", "conversation tree", palette),
+            searchable: true,
+            query: "",
+            visible: 8,
+            options: entries.map((entry) => ({
+                label: `${entry.prefix}${preview(entry.node)}`,
+                hint: stamp(entry.node.createdAt),
+                ...(entry.node.id === selectedId ? { value: "active" } : {}),
+            })),
+            index,
+        },
+        nodeIds: Object.freeze(entries.map((entry) => entry.node.id)),
+    });
+}
+export async function selectTimeline(session, choose) {
+    const timeline = timelinePicker(session.conversation, session.palette);
+    if (timeline.nodeIds.length === 0)
+        return false;
+    const index = await choose(timeline.picker);
+    const nodeId = index === undefined ? undefined : timeline.nodeIds[index];
+    if (nodeId === undefined || nodeId === session.conversation.activeNodeId)
+        return false;
+    session.conversation = session.conversation.select(nodeId);
+    session.usage = usageFromHistory(session.conversation.history);
+    return true;
+}
+function timelineEntries(conversation) {
+    const completed = conversation.nodes.filter((node) => node.settlement === "completed");
+    const completedIds = new Set(completed.map((node) => node.id));
+    const children = new Map();
+    for (const node of completed) {
+        let parentId = node.parentId;
+        while (parentId !== 0 && !completedIds.has(parentId)) {
+            parentId = conversation.node(parentId)?.parentId ?? 0;
+        }
+        const siblings = children.get(parentId) ?? [];
+        siblings.push(node);
+        children.set(parentId, siblings);
+    }
+    const entries = [];
+    const visit = (parentId, lanes) => {
+        const siblings = children.get(parentId) ?? [];
+        for (let index = 0; index < siblings.length; index++) {
+            const node = siblings[index];
+            const forks = siblings.length > 1;
+            const last = index === siblings.length - 1;
+            const hidden = Math.max(0, lanes.length - 4);
+            const lanePrefix = `${hidden === 0 ? "" : "…  "}${lanes.slice(hidden)
+                .map((closed) => closed ? "   " : "│  ").join("")}`;
+            entries.push({
+                node,
+                prefix: `${lanePrefix}${forks ? (last ? "└─ " : "├─ ") : "• "}`,
+            });
+            visit(node.id, forks ? [...lanes, last] : lanes);
+        }
+    };
+    visit(0, []);
+    return entries;
+}
+function preview(node) {
+    for (const message of node.messages) {
+        if (message.role !== "user")
+            continue;
+        const text = message.content.find((block) => block.kind === "text")?.text
+            .replace(/\s+/gu, " ").trim();
+        if (text !== undefined && text !== "")
+            return text.slice(0, 160);
+    }
+    return "Untitled turn";
+}
+function stamp(value) {
+    const date = new Date(value);
+    if (!Number.isFinite(date.getTime()))
+        return value.replace("T", " ").slice(0, 16);
+    const two = (part) => String(part).padStart(2, "0");
+    return `${two(date.getHours())}:${two(date.getMinutes())}`;
+}

package/dist/tui/app-state.js

@@ -13,5 +13,6 @@ export function appState() {
         draft: "",
         spin: 0,
         closeWhenIdle: false,
+        committedNodeId: 0,
     };
 }

package/dist/tui/app-workflows.js

@@ -3,10 +3,12 @@ import { handleCommand } from "../commands.js";
 import { runTurn } from "../controller.js";
 import { resolveContextPolicy } from "../context/capacity.js";
 import { compactContext } from "../context/compactor.js";
+import { compactSession } from "../context/manual.js";
 import { isContextOverflow, shouldResolveContextPolicy } from "../context/policy.js";
 import { updateSettings } from "../settings.js";
 import { saveTranscript } from "../transcript-export.js";
 import { recordAuxiliaryUsage, recordUsage } from "../usage.js";
+import { selectTimeline } from "../timeline.js";
 import { answerAt } from "./approve.js";
 import { cancel as cancelOpen } from "./overlay.js";
 import { controllerOptions, turnFailure } from "./session-view.js";
@@ -14,6 +16,10 @@ import { transcribe } from "./turn.js";
 const WAITING = "Waiting";
 export function appWorkflows(options) {
     const { session, state, permissions, feedback } = options;
+    const choose = (picker) => new Promise((resolve) => {
+        state.open = { picker, settle: resolve };
+        options.render();
+    });
     async function command(text) {
         const activity = options.startActivity("command", `Running ${text.split(/\s+/)[0]}`);
         if (activity === undefined)
@@ -26,10 +32,7 @@ export function appWorkflows(options) {
                     state.open = { help: true, settle: resolve };
                     options.render();
                 }),
-                choose: (picker) => new Promise((resolve) => {
-                    state.open = { picker, settle: resolve };
-                    options.render();
-                }),
+                choose,
                 dismiss: () => {
                     state.open = state.open === undefined ? undefined : cancelOpen(state.open);
                     options.render();
@@ -51,6 +54,7 @@ export function appWorkflows(options) {
                     state.follow = true;
                     state.unseen = 0;
                     state.lastMaxScroll = 0;
+                    state.committedNodeId = 0;
                 },
                 permissions,
                 exportTranscript: () => saveTranscript(options.transcriptRoot, state.blocks),
@@ -58,6 +62,27 @@ export function appWorkflows(options) {
                     await updateSettings(patch);
                 },
                 refreshSettings: options.refreshSettings,
+                timeline: async () => {
+                    const selected = await selectTimeline(session, choose);
+                    if (!selected)
+                        return "unchanged";
+                    options.replaceTranscript();
+                    return session.conversation.activeNodeId === state.committedNodeId
+                        ? "unchanged"
+                        : "selected";
+                },
+                compact: async () => {
+                    if (session.conversation.activeNodeId !== state.committedNodeId) {
+                        return "branch-pending";
+                    }
+                    return compactSession(session, {
+                        signal: activity.control.signal,
+                        onStatus: (status) => {
+                            state.status = status ?? activity.label;
+                            options.render();
+                        },
+                    });
+                },
             });
             if (outcome === "exit")
                 state.closeWhenIdle = true;
@@ -128,6 +153,7 @@ export function appWorkflows(options) {
             await session.persistence?.checkpoint(next);
             session.conversation = next;
             nodeId = next.activeNodeId;
+            state.committedNodeId = next.activeNodeId;
         };
         const compact = async (checkpoint, projected, reason, error) => {
             if (reason === "overflow" && (error === undefined || !isContextOverflow(error))) {