@giovannijecha/jecode 0.1.5-rc.2

package/dist/tools/shell.js

@@ -0,0 +1,139 @@
+// Shell tool. One command, captured output, a timeout, and a hard cap on how
+// much of it comes back.
+import { spawn } from "node:child_process";
+import { optionalInt, requireString } from "./args.js";
+import { credentialRedactor, redactCredentials, shellEnvironment } from "../credential-safety.js";
+const DEFAULT_TIMEOUT_MS = 120_000;
+const MAX_OUTPUT_CHARS = 30_000;
+export const runCommand = {
+    name: "run_command",
+    description: "Run a shell command starting in the workspace root and return its combined stdout " +
+        "and stderr. The shell is not a filesystem sandbox, so every call requires approval. Output is " +
+        "truncated past 30000 characters.",
+    dangerous: true,
+    input: {
+        type: "object",
+        properties: {
+            command: { type: "string", description: "The command line to run." },
+            timeout_ms: { type: "integer", description: "Kill the command after this long. Defaults to 120000." },
+        },
+        required: ["command"],
+    },
+    async run(args, ctx) {
+        const command = requireString(args, "command");
+        const timeoutMs = optionalInt(args, "timeout_ms") ?? DEFAULT_TIMEOUT_MS;
+        if (timeoutMs <= 0)
+            throw new Error('"timeout_ms" must be a positive integer');
+        const result = await execute(command, ctx.root, timeoutMs, ctx.signal);
+        const output = redactCredentials(result.output);
+        const summary = result.timedOut
+            ? `timed out after ${timeoutMs}ms`
+            : `exit ${result.code ?? "?"}`;
+        return {
+            output: output === "" ? `[${summary}]` : `${output}\n[${summary}]`,
+            summary,
+        };
+    },
+};
+function execute(command, cwd, timeoutMs, signal) {
+    if (signal?.aborted === true)
+        return Promise.reject(abortReason(signal));
+    return new Promise((resolve, reject) => {
+        const child = spawn(command, {
+            cwd,
+            env: shellEnvironment(),
+            shell: true,
+            windowsHide: true,
+            detached: process.platform !== "win32",
+        });
+        const output = capture();
+        let timedOut = false;
+        let aborted;
+        let settled = false;
+        let forceTimer;
+        const timer = setTimeout(() => {
+            timedOut = true;
+            stopTree(child.pid, false);
+            forceTimer = setTimeout(() => stopTree(child.pid, true), 500);
+        }, timeoutMs);
+        const onAbort = () => {
+            aborted = signal === undefined ? new Error("aborted") : abortReason(signal);
+            stopTree(child.pid, false);
+            forceTimer = setTimeout(() => stopTree(child.pid, true), 500);
+        };
+        signal?.addEventListener("abort", onAbort, { once: true });
+        const cleanup = () => {
+            clearTimeout(timer);
+            if (forceTimer !== undefined)
+                clearTimeout(forceTimer);
+            signal?.removeEventListener("abort", onAbort);
+        };
+        child.stdout.setEncoding("utf8");
+        child.stderr.setEncoding("utf8");
+        child.stdout.on("data", output.append);
+        child.stderr.on("data", output.append);
+        child.on("error", (error) => {
+            if (settled)
+                return;
+            settled = true;
+            cleanup();
+            reject(error);
+        });
+        child.on("close", (code) => {
+            if (settled)
+                return;
+            settled = true;
+            cleanup();
+            if (aborted !== undefined)
+                reject(aborted);
+            else
+                resolve({ output: output.value().trimEnd(), code, timedOut });
+        });
+    });
+}
+function capture() {
+    const half = MAX_OUTPUT_CHARS / 2;
+    const credentials = credentialRedactor();
+    let head = "";
+    let tail = "";
+    let total = 0;
+    const append = (chunk) => {
+        total += chunk.length;
+        const room = Math.max(0, half - head.length);
+        head += chunk.slice(0, room);
+        const rest = chunk.slice(room);
+        if (rest !== "")
+            tail = `${tail}${rest}`.slice(-half);
+    };
+    return {
+        append(chunk) {
+            append(credentials.write(chunk));
+        },
+        value() {
+            append(credentials.end());
+            if (total <= MAX_OUTPUT_CHARS)
+                return `${head}${tail}`;
+            const cut = total - head.length - tail.length;
+            return `${head}\n\n[... ${cut} characters cut ...]\n\n${tail}`;
+        },
+    };
+}
+function abortReason(signal) {
+    return signal.reason instanceof Error ? signal.reason : new Error("aborted");
+}
+function stopTree(pid, force) {
+    if (pid === undefined)
+        return;
+    if (process.platform === "win32") {
+        const args = ["/pid", String(pid), "/T", ...(force ? ["/F"] : [])];
+        const killer = spawn("taskkill", args, { windowsHide: true, stdio: "ignore" });
+        killer.on("error", () => undefined);
+        return;
+    }
+    try {
+        process.kill(-pid, force ? "SIGKILL" : "SIGTERM");
+    }
+    catch {
+        // The process may have exited between the timeout and this signal.
+    }
+}

package/dist/tools/text-boundary.js

@@ -0,0 +1,102 @@
+// Shared limits for tools that need to hold an entire text file in memory.
+import { constants } from "node:fs";
+import { lstat, open } from "node:fs/promises";
+export const MAX_EDITABLE_BYTES = 4_000_000;
+export const MAX_EDITABLE_CHARS = 1_000_000;
+export const MAX_EDITABLE_LINES = 20_000;
+const READ_CHUNK_BYTES = 64 * 1024;
+/** Read a regular UTF-8 file without allowing an unbounded allocation. */
+export async function readEditableText(file, options = {}) {
+    const label = options.label ?? "file";
+    let details;
+    try {
+        details = await lstat(file);
+    }
+    catch (error) {
+        if (options.missingAsEmpty === true && isMissing(error))
+            return "";
+        throw error;
+    }
+    if (!details.isFile())
+        throw new Error(`${label} must be a regular file`);
+    let handle;
+    try {
+        const flags = process.platform === "win32"
+            ? "r"
+            : constants.O_RDONLY | (constants.O_NONBLOCK ?? 0);
+        handle = await open(file, flags);
+    }
+    catch (error) {
+        if (options.missingAsEmpty === true && isMissing(error))
+            return "";
+        throw error;
+    }
+    try {
+        const stat = await handle.stat();
+        if (!stat.isFile())
+            throw new Error(`${label} must be a regular file`);
+        if (stat.size > MAX_EDITABLE_BYTES) {
+            throw limitError(label, `${MAX_EDITABLE_BYTES} UTF-8 bytes`);
+        }
+        const chunks = [];
+        let total = 0;
+        while (total <= MAX_EDITABLE_BYTES) {
+            const room = MAX_EDITABLE_BYTES + 1 - total;
+            const buffer = Buffer.allocUnsafe(Math.min(READ_CHUNK_BYTES, room));
+            const { bytesRead } = await handle.read(buffer, 0, buffer.length, total);
+            if (bytesRead === 0)
+                break;
+            chunks.push(buffer.subarray(0, bytesRead));
+            total += bytesRead;
+        }
+        if (total > MAX_EDITABLE_BYTES) {
+            throw limitError(label, `${MAX_EDITABLE_BYTES} UTF-8 bytes`);
+        }
+        const text = Buffer.concat(chunks, total).toString("utf8");
+        assertEditableText(text, label);
+        return text;
+    }
+    finally {
+        await handle.close();
+    }
+}
+/** Reject whole-file writes that exceed Jecode's mutation budget. */
+export function assertEditableText(text, label = "content") {
+    if (Buffer.byteLength(text, "utf8") > MAX_EDITABLE_BYTES) {
+        throw limitError(label, `${MAX_EDITABLE_BYTES} UTF-8 bytes`);
+    }
+    if (text.length > MAX_EDITABLE_CHARS) {
+        throw limitError(label, `${MAX_EDITABLE_CHARS} characters`);
+    }
+    if (lineCount(text) > MAX_EDITABLE_LINES) {
+        throw limitError(label, `${MAX_EDITABLE_LINES} lines`);
+    }
+}
+/** Check a replacement's size before constructing the resulting string. */
+export function assertReplacementFits(before, oldText, newText, replacements) {
+    const projectedChars = before.length + replacements * (newText.length - oldText.length);
+    if (projectedChars > MAX_EDITABLE_CHARS) {
+        throw limitError("edited content", `${MAX_EDITABLE_CHARS} characters`);
+    }
+    const projectedLines = lineCount(before) +
+        replacements * (newlineCount(newText) - newlineCount(oldText));
+    if (projectedLines > MAX_EDITABLE_LINES) {
+        throw limitError("edited content", `${MAX_EDITABLE_LINES} lines`);
+    }
+}
+function lineCount(text) {
+    return newlineCount(text) + 1;
+}
+function newlineCount(text) {
+    let lines = 0;
+    for (let index = text.indexOf("\n"); index !== -1; index = text.indexOf("\n", index + 1)) {
+        lines += 1;
+    }
+    return lines;
+}
+function limitError(label, limit) {
+    return new Error(`${label} exceeds the whole-file mutation limit of ${limit}`);
+}
+function isMissing(error) {
+    return error.code === "ENOENT";
+}

package/dist/tools/types.js

@@ -0,0 +1 @@
+export {};

package/dist/transcript-export.js

@@ -0,0 +1,11 @@
+// Write one automatically named transcript to Jecode's application root.
+import { atomicWrite } from "./atomic.js";
+import { assertDirectWritableInRoot, displayPath, resolveDirectWritableInRoot, resolveExistingInRoot, } from "./tools/paths.js";
+import { defaultTranscriptName, transcriptMarkdown } from "./transcript.js";
+export async function saveTranscript(applicationRoot, blocks, now = new Date()) {
+    const root = await resolveExistingInRoot(applicationRoot, ".");
+    const target = await resolveDirectWritableInRoot(root, defaultTranscriptName(now));
+    const validate = () => assertDirectWritableInRoot(root, target);
+    await atomicWrite(target, transcriptMarkdown(blocks), { validate });
+    return displayPath(root, target);
+}

package/dist/transcript.js

@@ -0,0 +1,49 @@
+// A portable transcript: screen blocks in, Markdown out.
+import { terminalText } from "./ui/terminal-text.js";
+export function defaultTranscriptName(now = new Date()) {
+    return `jecode-transcript-${now.toISOString().replace(/[-:]/g, "").replace(/\.\d{3}Z$/, "Z")}.md`;
+}
+export function transcriptMarkdown(blocks) {
+    const out = ["# jecode transcript", ""];
+    for (const block of blocks) {
+        switch (block.kind) {
+            case "user":
+                out.push("## You", "", safeMultiline(block.text), "");
+                break;
+            case "answer":
+                out.push("## Assistant", "", safeMultiline(block.text), "");
+                break;
+            case "reasoning":
+                out.push("<details>", "<summary>Reasoning</summary>", "", safeMultiline(block.text), "", "</details>", "");
+                break;
+            case "tool":
+                out.push(`- **${safeInline(block.name)}**${block.target === "" ? "" : ` \`${inlineCode(block.target)}\``}${block.right === "" ? "" : ` — ${safeInline(block.right)}`}`);
+                if ((block.body?.length ?? 0) > 0) {
+                    out.push("", "````text", ...(block.body ?? []).map(detail), "````", "");
+                }
+                break;
+            case "notice":
+                out.push(`> ${block.tone.toUpperCase()}: ${safeMultiline(block.text).replaceAll("\n", "\n> ")}`, "");
+                break;
+            case "list":
+                out.push(...block.items.map((item) => safeInline(item.text)), "");
+                break;
+        }
+    }
+    while (out[out.length - 1] === "")
+        out.pop();
+    return `${out.join("\n")}\n`;
+}
+function detail(row) {
+    const prefix = row.kind === "add" ? "+ " : row.kind === "del" ? "- " : row.kind === "keep" ? "  " : "";
+    return `${prefix}${safeInline(row.text)}`;
+}
+function inlineCode(text) {
+    return safeInline(text).replace(/`/g, "ˋ");
+}
+function safeInline(text) {
+    return terminalText(text);
+}
+function safeMultiline(text) {
+    return terminalText(text, { multiline: true });
+}

package/dist/tui/activity.js

@@ -0,0 +1,11 @@
+// One foreground operation owns cancellation and elapsed time.
+export function begin(kind, label, now = Date.now()) {
+    return { kind, label, control: new AbortController(), startedAt: now };
+}
+export function elapsed(activity, now = Date.now()) {
+    const seconds = Math.max(0, Math.floor((now - activity.startedAt) / 1_000));
+    if (seconds < 60)
+        return `${seconds}s`;
+    const minutes = Math.floor(seconds / 60);
+    return `${minutes}m ${String(seconds % 60).padStart(2, "0")}s`;
+}

package/dist/tui/app-input.js

@@ -0,0 +1,155 @@
+// Keyboard and pointer intent for the TUI shell.
+import { activate as activateCompletion, move as moveCompletion, selected as selectedCompletion, } from "./complete.js";
+import * as edit from "./editor.js";
+import { turnBlocker } from "./feedback.js";
+import { applyKey } from "./input.js";
+import * as overlay from "./overlay.js";
+import { toggleDetails } from "./session-view.js";
+const SCROLL_STEP = 8;
+const WHEEL_STEP = 3;
+export function appInput(options) {
+    const { session, state, feedback, actions } = options;
+    function handle(key) {
+        if (!options.live())
+            return;
+        // The wheel only changes what is visible. It never answers an open prompt.
+        if (key.name === "pointer") {
+            const wheel = key.pointer?.wheel;
+            if (wheel !== undefined)
+                options.scrollBy(wheel === "up" ? WHEEL_STEP : -WHEEL_STEP);
+            return;
+        }
+        if (state.feedback !== undefined)
+            feedback.dismiss();
+        if (state.open !== undefined) {
+            const outcome = overlay.handle(state.open, key);
+            state.open = outcome.open;
+            if (outcome.abort === true)
+                state.activity?.control.abort(new Error("interrupted"));
+            if (outcome.quit === true)
+                options.requestQuit();
+            return;
+        }
+        if (key.ctrl && key.name === "c") {
+            if (state.activity !== undefined)
+                state.activity.control.abort(new Error("interrupted"));
+            else
+                options.quit();
+            return;
+        }
+        if (key.ctrl && key.name === "d" && state.editor.text === "") {
+            options.requestQuit();
+            return;
+        }
+        switch (key.name) {
+            case "escape":
+                if (state.completing !== undefined) {
+                    state.completing = undefined;
+                    return;
+                }
+                state.activity?.control.abort(new Error("interrupted"));
+                return;
+            case "enter": {
+                if (state.completing !== undefined) {
+                    const completed = selectedCompletion(state.completing);
+                    if (completed !== undefined)
+                        state.editor = edit.of(completed);
+                    state.completing = undefined;
+                }
+                submit();
+                return;
+            }
+            case "tab": {
+                const completion = state.completing ?? activateCompletion(state.editor.text);
+                const completed = completion === undefined ? undefined : selectedCompletion(completion);
+                if (completed !== undefined) {
+                    state.editor = edit.of(completed);
+                    state.completing = undefined;
+                }
+                return;
+            }
+            case "up":
+                if (state.completing !== undefined) {
+                    state.completing = moveCompletion(state.completing, -1);
+                    return;
+                }
+                recall(-1);
+                return;
+            case "down":
+                if (state.completing !== undefined) {
+                    state.completing = moveCompletion(state.completing, 1);
+                    return;
+                }
+                recall(1);
+                return;
+            case "pageup":
+                options.scrollBy(SCROLL_STEP);
+                return;
+            case "pagedown":
+                options.scrollBy(-SCROLL_STEP);
+                return;
+            default:
+                break;
+        }
+        if (key.ctrl && key.name === "l") {
+            options.invalidate();
+            return;
+        }
+        if (key.ctrl && key.name === "o") {
+            const changed = toggleDetails(state.blocks);
+            if (changed !== undefined)
+                options.transcriptChanged(changed);
+            return;
+        }
+        const edited = applyKey(state.editor, key);
+        if (edited !== undefined) {
+            state.editor = edited;
+            state.completing = activateCompletion(edited.text);
+        }
+    }
+    function recall(step) {
+        if (state.past.length === 0)
+            return;
+        state.completing = undefined;
+        if (state.recall === -1) {
+            if (step > 0)
+                return;
+            state.draft = state.editor.text;
+            state.recall = state.past.length;
+        }
+        const next = state.recall + step;
+        if (next >= state.past.length) {
+            state.recall = -1;
+            state.editor = edit.of(state.draft);
+            return;
+        }
+        state.recall = Math.max(0, next);
+        state.editor = edit.of(state.past[state.recall]);
+    }
+    function submit() {
+        const text = state.editor.text.trim();
+        if (text === "" || state.activity !== undefined)
+            return;
+        const isCommand = text.startsWith("/");
+        if (!isCommand) {
+            const blocker = turnBlocker(session);
+            if (blocker !== undefined) {
+                feedback.show(blocker);
+                return;
+            }
+        }
+        state.editor = edit.EMPTY;
+        state.recall = -1;
+        state.draft = "";
+        state.completing = undefined;
+        state.past.push(text);
+        state.scroll = 0;
+        state.follow = true;
+        state.unseen = 0;
+        if (isCommand)
+            void actions.command(text);
+        else
+            void actions.turn(text);
+    }
+    return { handle };
+}

package/dist/tui/app-state.js

@@ -0,0 +1,17 @@
+// Mutable screen state shared by the shell, input, and foreground workflows.
+import * as edit from "./editor.js";
+export function appState() {
+    return {
+        blocks: [],
+        editor: edit.EMPTY,
+        scroll: 0,
+        follow: true,
+        unseen: 0,
+        lastMaxScroll: 0,
+        past: [],
+        recall: -1,
+        draft: "",
+        spin: 0,
+        closeWhenIdle: false,
+    };
+}

package/dist/tui/app-workflows.js

@@ -0,0 +1,105 @@
+// Foreground command and model-turn workflows for the TUI shell.
+import { handleCommand } from "../commands.js";
+import { runTurn } from "../controller.js";
+import { updateSettings } from "../settings.js";
+import { saveTranscript } from "../transcript-export.js";
+import { recordUsage } from "../usage.js";
+import { answerAt, scopeFor } from "./approve.js";
+import { controllerOptions, turnFailure } from "./session-view.js";
+import { transcribe } from "./turn.js";
+const WAITING = "Waiting";
+export function appWorkflows(options) {
+    const { session, state, allowed, feedback } = options;
+    async function command(text) {
+        const activity = options.startActivity("command", `Running ${text.split(/\s+/)[0]}`);
+        if (activity === undefined)
+            return;
+        try {
+            const outcome = await handleCommand(text, session, {
+                emit: options.commandOutput,
+                signal: activity.control.signal,
+                choose: (picker) => new Promise((resolve) => {
+                    state.open = { picker, settle: resolve };
+                    options.render();
+                }),
+                type: (field) => new Promise((resolve) => {
+                    state.open = { field, settle: resolve };
+                    options.render();
+                }),
+                status: (said) => {
+                    state.status = said ?? activity.label;
+                    options.render();
+                },
+                reset: () => {
+                    state.blocks.splice(0);
+                    state.past.length = 0;
+                    allowed.clear();
+                    state.scroll = 0;
+                    state.follow = true;
+                    state.unseen = 0;
+                    state.lastMaxScroll = 0;
+                },
+                permissions: () => [...allowed].map(([key, label]) => ({ key, label })),
+                revokePermission: (key) => {
+                    if (key === undefined)
+                        allowed.clear();
+                    else
+                        allowed.delete(key);
+                },
+                exportTranscript: () => saveTranscript(options.transcriptRoot, state.blocks),
+                saveSettings: async (patch) => {
+                    await updateSettings(patch);
+                },
+                refreshSettings: options.refreshSettings,
+            });
+            if (outcome === "exit")
+                state.closeWhenIdle = true;
+        }
+        catch (error) {
+            feedback.show({
+                text: activity.control.signal.aborted ? "interrupted" : error.message,
+                tone: activity.control.signal.aborted ? "warn" : "error",
+                timeoutMs: activity.control.signal.aborted ? 4_200 : 6_000,
+            });
+        }
+        finally {
+            options.finishActivity(activity);
+        }
+    }
+    async function turn(text) {
+        const activity = options.startActivity("turn", WAITING);
+        if (activity === undefined)
+            return;
+        options.emit({ kind: "user", text });
+        session.history.push({ role: "user", content: [{ kind: "text", text }] });
+        const events = transcribe({
+            emit: options.emit,
+            render: options.render,
+            palette: session.palette,
+            approved: (call) => session.config.autoApprove || allowed.has(scopeFor(call).key),
+            remember: (call) => {
+                const scope = scopeFor(call);
+                allowed.set(scope.key, scope.summary);
+            },
+            ask: (prompt, settle) => {
+                state.open = { picker: prompt, settle: (index) => settle(answerAt(index)) };
+                options.render();
+            },
+            status: (text) => {
+                state.status = text;
+            },
+            usage: (usage) => recordUsage(session.usage, usage),
+        });
+        try {
+            await runTurn(session.history, controllerOptions(session), events, activity.control.signal);
+        }
+        catch (error) {
+            options.emit(turnFailure(session, error, activity.control.signal.aborted));
+        }
+        finally {
+            events.finish();
+            options.finishActivity(activity);
+        }
+    }
+    return { command, turn };
+}