@giovannijecha/jecode 0.8.4 → 0.8.6

package/dist/settings-command.js

@@ -69,26 +69,31 @@ function settingsItems(values) {
             option: {
                 label: "model",
                 value: `${providerLabel(values.provider)} · ${values.model || "choose a model"}`,
+                description: "Choose the provider and model used for subsequent requests.",
             },
         },
-        { action: "effort", option: { label: "effort", value: values.effort } },
+        { action: "effort", option: { label: "effort", value: values.effort,
+                description: "Set the saved reasoning effort for model requests." } },
         ...(values.maxTokens === undefined
             ? []
             : [{
                     action: "maxTokens",
-                    option: { label: "max output tokens", value: String(values.maxTokens) },
+                    option: { label: "max output tokens", value: String(values.maxTokens),
+                        description: "Limit the output tokens requested from the model in each response." },
                 }]),
         {
             action: "compactionPercent",
-            option: { label: "context compaction", value: `${values.compactionPercent}%` },
+            option: { label: "context compaction", value: `${values.compactionPercent}%`,
+                description: "Compact model context near this share of its usable window. The transcript stays complete." },
         },
         {
             action: "reducedMotion",
-            option: { label: "reduced motion", value: values.reducedMotion ? "on" : "off" },
+            option: { label: "reduced motion", value: values.reducedMotion ? "on" : "off",
+                description: "Keep decorative movement still while output continues to update." },
         },
         {
             action: "providers",
-            option: { label: "providers", hint: "manage connections" },
+            option: { label: "providers", hint: "manage connections", description: "Manage API keys and account connections." },
         },
     ];
 }

package/dist/settings.js

@@ -1,14 +1,14 @@
 // Persistent, non-secret defaults for interactive and batch sessions.
-import { chmod, mkdir } from "node:fs/promises";
 import * as path from "node:path";
 import { atomicWrite } from "./atomic.js";
+import { assertDirectoryAnchor, captureDirectDirectorySync, preparePrivateDirectory, } from "./directory-anchor.js";
 import { MAX_COMPACTION_PERCENT, MIN_COMPACTION_PERCENT } from "./context/policy.js";
 import { EFFORTS } from "./effort.js";
 import { providerNames } from "./providers/index.js";
-import { parseOllamaEndpoint } from "./providers/ollama-endpoint.js";
+import { isLegacyOllamaCloudHost, OLLAMA_CLOUD_HOST } from "./providers/ollama-endpoint.js";
 import { withStoreLock } from "./store-lock.js";
 import { userDataLabel, userDataPath } from "./user-data.js";
-import { assertStoreText, readBoundedJsonSync, USER_STORE_LIMITS } from "./user-store.js";
+import { assertStoreText, readBoundedJsonForMutationSync, readBoundedJsonSync, USER_STORE_LIMITS, } from "./user-store.js";
 export { EFFORTS } from "./effort.js";
 let saved;
 export function readSettings() {
@@ -17,19 +17,23 @@ export function readSettings() {
     return copy(saved);
 }
 export async function updateSettings(patch) {
+    assertRetiredOllamaHost(patch);
     const file = settingsPath();
     const directory = path.dirname(file);
-    await mkdir(directory, { recursive: true, mode: 0o700 });
-    if (process.platform !== "win32")
-        await chmod(directory, 0o700);
-    return withStoreLock(file, async () => {
-        const next = normalize({ ...readStore(file), ...patch });
+    const anchor = await preparePrivateDirectory(directory, "settings store directory");
+    const anchoredFile = path.join(anchor.path, path.basename(file));
+    return withStoreLock(anchoredFile, async () => {
+        const next = normalize({ ...readStoreForMutation(anchoredFile, anchor), ...patch });
+        delete next.ollamaHost;
         const text = `${JSON.stringify(next, null, 2)}\n`;
         assertStoreText(text, USER_STORE_LIMITS.settingsBytes);
-        await atomicWrite(file, text, { mode: 0o600 });
+        await atomicWrite(anchoredFile, text, {
+            mode: 0o600,
+            validate: async () => assertDirectoryAnchor(anchor),
+        });
         saved = next;
         return file;
-    });
+    }, undefined, async () => assertDirectoryAnchor(anchor));
 }
 export function settingsPath() {
     return userDataPath("settings.json");
@@ -43,21 +47,69 @@ export function reloadSettings() {
 }
 function readStore(file = settingsPath()) {
     try {
-        return normalize(readBoundedJsonSync(file, USER_STORE_LIMITS.settingsBytes));
+        const directory = captureDirectDirectorySync(path.dirname(file), "settings store directory");
+        const anchoredFile = path.join(directory.path, path.basename(file));
+        return normalize(readBoundedJsonSync(anchoredFile, USER_STORE_LIMITS.settingsBytes, directory));
     }
     catch {
-        // Missing, unreadable, and malformed stores all fall back safely. A bad
-        // preference must never prevent the agent from starting.
+        // Missing, unreadable, and malformed stores fall back safely. Parsed
+        // retired endpoint markers survive normalization for startup validation.
         return {};
     }
 }
+function readStoreForMutation(file, directory) {
+    const value = readBoundedJsonForMutationSync(file, USER_STORE_LIMITS.settingsBytes, "settings store", directory);
+    if (value === undefined)
+        return {};
+    if (!record(value))
+        throw new Error("settings store has an unsupported structure");
+    assertMutableSettings(value);
+    return normalize(value);
+}
+function assertMutableSettings(value) {
+    const current = new Set([
+        "provider",
+        "models",
+        "ollamaHost",
+        "effort",
+        "reducedMotion",
+        "maxTokens",
+        "compactionPercent",
+    ]);
+    const retired = new Set(["theme", "palette", "maxSteps"]);
+    if (Object.keys(value).some((key) => !current.has(key) && !retired.has(key))) {
+        throw new Error("settings store has an unsupported structure");
+    }
+    const providers = providerNames();
+    if ("provider" in value && member(value["provider"], providers) === undefined) {
+        throw new Error("settings store has an invalid provider");
+    }
+    if ("models" in value) {
+        const models = value["models"];
+        if (!record(models) || Object.keys(models).some((provider) => !providers.includes(provider)) ||
+            Object.values(models).some((model) => !boundedNonempty(model, USER_STORE_LIMITS.model)))
+            throw new Error("settings store has invalid models");
+    }
+    assertRetiredOllamaHost(value);
+    if ("effort" in value && member(value["effort"], EFFORTS) === undefined) {
+        throw new Error("settings store has an invalid reasoning effort");
+    }
+    if ("reducedMotion" in value && typeof value["reducedMotion"] !== "boolean") {
+        throw new Error("settings store has an invalid reduced-motion preference");
+    }
+    if ("maxTokens" in value && positiveInteger(value["maxTokens"]) === undefined) {
+        throw new Error("settings store has an invalid token limit");
+    }
+    if ("compactionPercent" in value && percentage(value["compactionPercent"]) === undefined)
+        throw new Error("settings store has an invalid compaction threshold");
+}
 function normalize(value) {
     if (!record(value))
         return {};
     const providers = providerNames();
     const provider = member(value["provider"], providers);
     const models = modelsOf(value["models"], providers);
-    const ollamaHost = endpoint(value["ollamaHost"]);
+    const ollamaHost = "ollamaHost" in value ? legacyOllamaHost(value["ollamaHost"]) : undefined;
     const effort = member(value["effort"], EFFORTS);
     const reducedMotion = typeof value["reducedMotion"] === "boolean" ? value["reducedMotion"] : undefined;
     const maxTokens = positiveInteger(value["maxTokens"]);
@@ -81,14 +133,15 @@ function modelsOf(value, providers) {
 function member(value, values) {
     return typeof value === "string" && values.includes(value) ? value : undefined;
 }
-function endpoint(value) {
-    if (!boundedNonempty(value, USER_STORE_LIMITS.endpoint))
-        return undefined;
-    try {
-        return parseOllamaEndpoint(value).baseUrl;
-    }
-    catch {
-        return undefined;
+function legacyOllamaHost(value) {
+    if (isLegacyOllamaCloudHost(value))
+        return OLLAMA_CLOUD_HOST;
+    // Even an invalid retired value must not disappear and enable cloud use.
+    return boundedNonempty(value, USER_STORE_LIMITS.endpoint) ? value : "unsupported legacy Ollama endpoint";
+}
+function assertRetiredOllamaHost(value) {
+    if ("ollamaHost" in value && !isLegacyOllamaCloudHost(value.ollamaHost)) {
+        throw new Error("settings store has a retired Ollama endpoint; remove ollamaHost from settings.json to use Ollama API");
     }
 }
 function boundedNonempty(value, max) {

package/dist/stable-directory.js

@@ -0,0 +1,148 @@
+// Bounded directory enumeration with post-open identity and root checks.
+import { lstat, opendir, realpath } from "node:fs/promises";
+import * as path from "node:path";
+import { stableFileExpectation } from "./bounded-file.js";
+import { fileIdentity, sameFileIdentity } from "./file-identity.js";
+export class StableDirectoryError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "StableDirectoryError";
+    }
+}
+export async function readStableDirectory(root, directory, options) {
+    if (!Number.isSafeInteger(options.maxEntries) || options.maxEntries < 0) {
+        throw new RangeError("directory entry limit is invalid");
+    }
+    throwIfAborted(options.signal);
+    const canonicalRoot = await realpath(root);
+    const canonicalDirectory = await realpath(directory);
+    if (!inside(canonicalRoot, canonicalDirectory))
+        throw escaped();
+    const before = await lstat(canonicalDirectory, { bigint: true });
+    requireDirectory(before);
+    await options.beforeOpen?.();
+    throwIfAborted(options.signal);
+    const names = [];
+    let capped = false;
+    try {
+        const handle = await opendir(canonicalDirectory);
+        for await (const entry of handle) {
+            throwIfAborted(options.signal);
+            if (names.length >= options.maxEntries) {
+                capped = true;
+                break;
+            }
+            if (directName(entry.name))
+                names.push(entry.name);
+        }
+    }
+    catch (error) {
+        if (changedPath(error))
+            throw changed();
+        throw error;
+    }
+    await assertDirectory(canonicalRoot, canonicalDirectory, before);
+    const entries = [];
+    for (const name of names) {
+        throwIfAborted(options.signal);
+        const entry = await inspectEntry(canonicalRoot, canonicalDirectory, name);
+        if (entry !== undefined)
+            entries.push(entry);
+    }
+    await assertDirectory(canonicalRoot, canonicalDirectory, before);
+    entries.sort((left, right) => left.name.localeCompare(right.name));
+    return { entries, capped };
+}
+async function inspectEntry(root, directory, name) {
+    const target = path.join(directory, name);
+    let before;
+    try {
+        before = await lstat(target, { bigint: true });
+    }
+    catch (error) {
+        if (changedPath(error))
+            return undefined;
+        throw error;
+    }
+    if (before.isSymbolicLink())
+        return undefined;
+    const kind = before.isFile() ? "file" : before.isDirectory() ? "directory" : undefined;
+    if (kind === undefined)
+        return undefined;
+    let canonical;
+    try {
+        canonical = await realpath(target);
+    }
+    catch (error) {
+        if (changedPath(error))
+            return undefined;
+        throw error;
+    }
+    if (!inside(root, canonical) || !samePath(target, canonical))
+        return undefined;
+    let after;
+    try {
+        after = await lstat(target, { bigint: true });
+    }
+    catch (error) {
+        if (changedPath(error))
+            return undefined;
+        throw error;
+    }
+    if (after.isSymbolicLink() ||
+        !sameFileIdentity(fileIdentity(before), fileIdentity(after)) ||
+        (kind === "file" ? !after.isFile() : !after.isDirectory()))
+        return undefined;
+    return kind === "file"
+        ? { name, kind, expected: stableFileExpectation(after) }
+        : { name, kind };
+}
+async function assertDirectory(root, directory, expected) {
+    let current;
+    let canonical;
+    try {
+        [current, canonical] = await Promise.all([
+            lstat(directory, { bigint: true }),
+            realpath(directory),
+        ]);
+    }
+    catch (error) {
+        if (changedPath(error))
+            throw changed();
+        throw error;
+    }
+    requireDirectory(current);
+    if (!inside(root, canonical) || !samePath(directory, canonical) ||
+        !sameFileIdentity(fileIdentity(expected), fileIdentity(current)))
+        throw changed();
+}
+function requireDirectory(details) {
+    if (details.isSymbolicLink() || !details.isDirectory())
+        throw changed();
+}
+function directName(name) {
+    return name !== "." && name !== ".." && path.basename(name) === name;
+}
+function inside(root, target) {
+    const relative = path.relative(root, target);
+    return relative === "" ||
+        (!path.isAbsolute(relative) && relative !== ".." && !relative.startsWith(`..${path.sep}`));
+}
+function samePath(left, right) {
+    return path.relative(left, right) === "";
+}
+function changedPath(error) {
+    const code = error.code;
+    return code === "ENOENT" || code === "ENOTDIR" || code === "ELOOP";
+}
+function changed() {
+    return new StableDirectoryError("directory changed while it was being listed");
+}
+function escaped() {
+    return new StableDirectoryError("directory escapes the workspace root");
+}
+function throwIfAborted(signal) {
+    if (signal?.aborted !== true)
+        return;
+    throw signal.reason instanceof Error ? signal.reason : new Error("aborted");
+}

package/dist/start.js

@@ -6,7 +6,7 @@ import { loadConfig } from "./config.js";
 import { ConversationTree } from "./conversation.js";
 import { parseLaunch } from "./launch.js";
 import { systemPrompt } from "./prompt.js";
-import { configureProviders, selectProvider } from "./providers/index.js";
+import { selectProvider } from "./providers/index.js";
 import { SessionPersistence } from "./sessions/runtime.js";
 import { DurableSessionStore } from "./sessions/store.js";
 import { builtinTools } from "./tools/index.js";
@@ -23,7 +23,6 @@ export async function start(args = process.argv.slice(2), environment = {}) {
         return;
     const launch = parseLaunch(args);
     const config = loadConfig(launch.configArgs);
-    configureProviders(config);
     const provider = selectProvider(config.providerId);
     const hasScreen = environment.interactive?.() ?? interactive();
     if (launch.kind === "resume" && !hasScreen) {

package/dist/store-lock.js

@@ -3,121 +3,105 @@
 // Every writer rereads inside the lock. That prevents two Jecode processes
 // from replacing unrelated settings, API keys, or rotated OAuth credentials
 // with snapshots they cached before the other process wrote.
-import { randomUUID } from "node:crypto";
-import { mkdir, open, readFile, rmdir, stat, unlink } from "node:fs/promises";
 import * as path from "node:path";
+import { lstat } from "node:fs/promises";
+import { BoundedFileError, readBoundedText } from "./bounded-file.js";
+import { pidIsAlive, ProcessLeaseError, processLeaseToken, tryAcquireProcessLease, } from "./process-lease.js";
 const WAIT_MS = 50;
 const WAIT_LIMIT_MS = 20_000;
 const STALE_MS = 60_000;
-export async function withStoreLock(file, body, signal) {
+const LEGACY_OWNER_BYTES = 256;
+export async function withStoreLock(file, body, signal, validate) {
     throwIfAborted(signal);
+    await validate?.();
     const directory = `${file}.lock`;
-    const token = `${process.pid}:${randomUUID()}`;
+    const token = processLeaseToken();
     const started = Date.now();
-    while (!(await acquire(directory, token))) {
+    let lease;
+    while (lease === undefined) {
+        await validate?.();
+        try {
+            lease = await tryAcquireProcessLease(directory, token, {
+                staleMs: STALE_MS,
+                setupGraceMs: 1_000,
+            });
+        }
+        catch (error) {
+            if (!(error instanceof ProcessLeaseError))
+                throw error;
+            throw await incompatibleLock(directory, file);
+        }
+        if (lease !== undefined)
+            break;
         if (signal?.aborted === true)
             throw abortReason(signal);
         if (Date.now() - started >= WAIT_LIMIT_MS) {
             throw new Error(`timed out waiting for ${path.basename(file)}`);
         }
-        await recoverStale(directory);
         await wait(WAIT_MS, signal);
     }
+    let primaryFailure;
     try {
         throwIfAborted(signal);
+        await lease.assertOwned();
+        await validate?.();
         return await body();
     }
-    finally {
-        await release(directory, token);
+    catch (error) {
+        primaryFailure = error;
+        throw error;
     }
-}
-async function acquire(directory, token) {
-    let created = false;
-    try {
-        await mkdir(directory, { mode: 0o700 });
-        created = true;
-        const owner = await open(path.join(directory, "owner"), "wx", 0o600);
+    finally {
         try {
-            await owner.writeFile(token, "utf8");
-            await owner.sync();
+            if (!(await lease.release()) && primaryFailure === undefined) {
+                throw new Error("store lock ownership was lost");
+            }
         }
-        finally {
-            await owner.close();
+        catch (error) {
+            if (primaryFailure === undefined)
+                throw error;
         }
-        return true;
-    }
-    catch (error) {
-        if (!created && error.code === "EEXIST")
-            return false;
-        if (created)
-            await removeLock(directory);
-        throw error;
     }
 }
-async function recoverStale(directory) {
-    try {
-        const details = await stat(directory);
-        if (Date.now() - details.mtimeMs < STALE_MS)
-            return;
-        if (await ownerIsAlive(directory))
-            return;
-        // Remove the owner first, then the now-empty directory. `rmdir` cannot
-        // erase a fresh lock acquired after another waiter wins this recovery,
-        // whereas renaming the shared path can steal that new lock in an ABA race.
-        await removeLock(directory);
-    }
-    catch (error) {
-        const code = error.code;
-        if (code !== "ENOENT" && code !== "EACCES" && code !== "EPERM")
-            throw error;
+async function incompatibleLock(directory, file) {
+    const legacy = await legacyOwner(directory);
+    if (legacy !== undefined) {
+        if (legacy.pid !== undefined && pidIsAlive(legacy.pid)) {
+            return new Error(`${path.basename(file)} is locked by an older Jecode process ` +
+                `(PID ${legacy.pid}) — close it and retry`);
+        }
+        return new Error(`${path.basename(file)} has an incompatible legacy lock — close older Jecode ` +
+            `processes, then remove this exact lock directory and retry: ${directory}`);
     }
+    return new Error(`${path.basename(file)} has an unsafe lock — inspect this exact directory before retrying: ` +
+        directory);
 }
-async function ownerIsAlive(directory) {
-    let token;
-    try {
-        token = await readFile(path.join(directory, "owner"), "utf8");
-    }
-    catch (error) {
-        const code = error.code;
-        if (code === "ENOENT")
-            return false;
-        if (code === "EACCES" || code === "EPERM")
-            return true;
-        throw error;
-    }
-    const match = /^([1-9]\d*):/.exec(token.trim());
-    if (match === null)
-        return false;
-    const pid = Number(match[1]);
-    if (!Number.isSafeInteger(pid) || pid > 0x7fff_ffff)
-        return false;
+async function legacyOwner(directory) {
+    const owner = path.join(directory, "owner");
     try {
-        process.kill(pid, 0);
-        return true;
+        const details = await lstat(owner, { bigint: true });
+        if (details.isSymbolicLink() || !details.isFile() ||
+            details.size > BigInt(LEGACY_OWNER_BYTES))
+            return { pid: undefined };
+        const token = (await readBoundedText(owner, LEGACY_OWNER_BYTES, {
+            label: "legacy store lock",
+        })).trim();
+        const match = /^([1-9]\d*):/.exec(token);
+        if (match === null)
+            return { pid: undefined };
+        const pid = Number(match[1]);
+        return Number.isSafeInteger(pid) && pid <= 0x7fff_ffff
+            ? { pid }
+            : { pid: undefined };
     }
     catch (error) {
-        // ESRCH is the one portable proof that the owner no longer exists.
-        // Permission failures and unknown platform errors must not authorize a
-        // second writer to enter the same store.
-        return error.code !== "ESRCH";
+        if (error.code === "ENOENT")
+            return undefined;
+        if (error instanceof BoundedFileError)
+            return { pid: undefined };
+        return undefined;
     }
 }
-async function release(directory, token) {
-    try {
-        const owner = path.join(directory, "owner");
-        if ((await readFile(owner, "utf8")) !== token)
-            return;
-        await unlink(owner);
-        await rmdir(directory);
-    }
-    catch {
-        // A recovered stale lock or an already-removed directory is no longer ours.
-    }
-}
-async function removeLock(directory) {
-    await unlink(path.join(directory, "owner")).catch(() => undefined);
-    await rmdir(directory).catch(() => undefined);
-}
 function wait(ms, signal) {
     return new Promise((resolve, reject) => {
         if (signal?.aborted === true) {

package/dist/tools/args.js

@@ -24,8 +24,8 @@ export function optionalInt(args, name) {
     if (value === undefined || value === null)
         return undefined;
     const n = typeof value === "string" ? Number(value) : value;
-    if (typeof n !== "number" || !Number.isInteger(n)) {
-        throw new Error(`"${name}" must be an integer`);
+    if (typeof n !== "number" || !Number.isSafeInteger(n)) {
+        throw new Error(`"${name}" must be a safe integer`);
     }
     return n;
 }