allaboard 0.0.0-stage → 0.4.0

package/dist/core/footer.js

@@ -0,0 +1,313 @@
+/** The context line under every reply as data: git state, usage limits, tokens and the fields. */
+import { spawn } from "node:child_process";
+import { getLogger } from "../log.js";
+import { strip } from "../text.js";
+import { errorName } from "../values.js";
+export const logger = getLogger("allaboard.core.footer");
+export const USAGE_TTL = 300_000;
+// For every git call of one footer together: the reply waits for it.
+export const GIT_TIMEOUT = 5_000;
+// ` 2 files changed, 42 insertions(+), 10 deletions(-)`, as every --shortstat writes it, git 2.54
+// (2026-09-27).
+const SHORTSTAT_INSERTIONS = /(\d+) insertions?\(\+\)/;
+const SHORTSTAT_DELETIONS = /(\d+) deletions?\(-\)/;
+// Variables of an outer git (a hook) that would send ours elsewhere.
+const GIT_REDIRECTS = ["GIT_DIR", "GIT_WORK_TREE", "GIT_INDEX_FILE"];
+const MINUTE_MS = 60_000;
+/**
+ * The usage cache: `/usage` costs a model call on a client of its own, so it is read at most once
+ * in `ttl` unless `invalidate` says the limits moved.
+ */
+export class UsageCache {
+    current = null;
+    fetch;
+    ttl;
+    clock;
+    warn;
+    fetchedAt = null;
+    refreshing = false;
+    constructor(fetch, options = {}) {
+        this.fetch = fetch;
+        this.ttl = options.ttl ?? USAGE_TTL;
+        this.clock = options.clock ?? (() => performance.now());
+        this.warn = options.warn ?? ((message) => logger.warning(message));
+    }
+    invalidate() {
+        this.fetchedAt = null;
+    }
+    /** Refresh when older than the TTL; a failure keeps the old value and waits a full TTL. */
+    async refreshIfStale() {
+        if (this.refreshing) {
+            return;
+        }
+        this.refreshing = true;
+        try {
+            if (this.fetchedAt !== null && this.clock() - this.fetchedAt < this.ttl) {
+                return;
+            }
+            try {
+                this.current = await this.fetch();
+            }
+            catch (error) {
+                // The footer is optional: never let it break a reply. The name only, never the text.
+                this.warn(`usage refresh failed: ${errorName(error)}`);
+            }
+            this.fetchedAt = this.clock();
+        }
+        finally {
+            this.refreshing = false;
+        }
+    }
+}
+/**
+ * `git` on `repository`: its output, or null when it fails. The caller holds the time limit
+ * (`gitState` here, `openfile` for `!open`) through `signal`, which kills the process and
+ * rejects with its reason, and chooses commands that never write the index (see `changesOf`).
+ */
+export function runGit(repository, args, signal) {
+    if (repository.gitDir === null) {
+        return Promise.resolve(null);
+    }
+    const env = { ...process.env };
+    for (const name of GIT_REDIRECTS) {
+        delete env[name];
+    }
+    return new Promise((resolve, reject) => {
+        if (signal?.aborted) {
+            reject(signal.reason);
+            return;
+        }
+        const child = spawn("git", [
+            // A diff must not run the repo's own fsmonitor command.
+            "-c",
+            "core.fsmonitor=false",
+            // Named, never found: git left to search from the folder would take a planted `.git`
+            // file, a bare layout or a `core.worktree` at its word (git(1), `--git-dir`).
+            "--git-dir",
+            repository.gitDir,
+            ...args,
+        ], { cwd: repository.root, env, stdio: ["ignore", "pipe", "ignore"] });
+        const chunks = [];
+        const onAbort = () => {
+            // Also when the time limit or the session closing cancels the footer: no git left running.
+            child.kill("SIGKILL");
+            reject(signal?.reason);
+        };
+        signal?.addEventListener("abort", onAbort, { once: true });
+        child.stdout.on("data", (chunk) => chunks.push(chunk));
+        child.once("error", () => {
+            signal?.removeEventListener("abort", onAbort);
+            resolve(null);
+        });
+        child.once("close", (code) => {
+            signal?.removeEventListener("abort", onAbort);
+            resolve(code === 0 ? Buffer.concat(chunks).toString("utf8") : null);
+        });
+    });
+}
+/** Insertions and deletions from a `--shortstat`, which leaves out a zero count. */
+export function shortstatLines(out) {
+    const insertions = SHORTSTAT_INSERTIONS.exec(out);
+    const deletions = SHORTSTAT_DELETIONS.exec(out);
+    return [insertions ? Number(insertions[1]) : 0, deletions ? Number(deletions[1]) : 0];
+}
+/**
+ * Lines inserted and deleted since the last commit, staged and unstaged, as ccstatusline's
+ * git-changes counts them for the terminal (untracked files not counted). Null where there is
+ * no work tree.
+ *
+ * Plumbing only: `git diff` refreshes and rewrites the index under `index.lock` (measured on
+ * git 2.54, `--no-optional-locks` included), and a lock left by a killed diff would stop every
+ * `git add` and commit in the repo. `diff-files` and `diff-index` never write it.
+ *
+ * A submodule counts by its commit alone. Without `--ignore-submodules=dirty` git runs
+ * `git status` inside every nested repository the index names, under that repository's own
+ * config and filters (measured on git 2.54, 2026-10-04).
+ */
+async function changesOf(repository, signal) {
+    const unstaged = await runGit(repository, ["diff-files", "--shortstat", "--ignore-submodules=dirty"], signal);
+    if (unstaged === null) {
+        return null;
+    }
+    // `--`: git runs at the root, where a file named HEAD would make the revision ambiguous.
+    let staged = await runGit(repository, ["diff-index", "--cached", "--shortstat", "HEAD", "--"], signal);
+    if (staged === null) {
+        // No commit yet: what is staged is compared with the empty tree, as `git diff --cached`.
+        const empty = await runGit(repository, ["hash-object", "-t", "tree", "/dev/null"], signal);
+        if (empty === null) {
+            return null;
+        }
+        staged = await runGit(repository, ["diff-index", "--cached", "--shortstat", empty.trim()], signal);
+        if (staged === null) {
+            return null;
+        }
+    }
+    const [added, removed] = shortstatLines(unstaged);
+    const [addedStaged, removedStaged] = shortstatLines(staged);
+    return [added + addedStaged, removed + removedStaged];
+}
+/** `promise`, or the signal's reason when it aborts first. */
+function until(promise, signal) {
+    return new Promise((resolve, reject) => {
+        if (signal.aborted) {
+            reject(signal.reason);
+            return;
+        }
+        const onAbort = () => reject(signal.reason);
+        signal.addEventListener("abort", onAbort, { once: true });
+        promise.then(resolve, reject).finally(() => signal.removeEventListener("abort", onAbort));
+    });
+}
+/**
+ * The branch and the changes of the repository holding `here`, each null when unknown.
+ *
+ * `repository` answers only for a repository the owner trusted in Claude Code
+ * (`trustedRepository`): anywhere else no git runs, since a diff runs the filters a repository's
+ * config names. Every call shares one `timeout` (milliseconds).
+ */
+export async function gitState(here, repository, timeout = GIT_TIMEOUT) {
+    let branch = null;
+    let changes = null;
+    const limit = new AbortController();
+    const timer = setTimeout(() => limit.abort(new Error("git timeout")), timeout);
+    const { signal } = limit;
+    try {
+        const found = await until(repository(here), signal);
+        if (found === null || found.gitDir === null) {
+            return [null, null];
+        }
+        const out = await runGit(found, ["branch", "--show-current"], signal);
+        branch = out ? strip(out) || null : null;
+        if (!found.insideGitDir) {
+            changes = await changesOf(found, signal);
+        }
+    }
+    catch (error) {
+        // What the limit cut off stays unknown; anything else is not ours to hide.
+        if (!signal.aborted) {
+            throw error;
+        }
+    }
+    finally {
+        clearTimeout(timer);
+    }
+    return [branch, changes];
+}
+/** The tokens of a turn summed over its models; null when it used none. */
+export function sessionTokens(tokens) {
+    const models = Object.values(tokens);
+    if (models.length === 0) {
+        return null;
+    }
+    return models.reduce((sum, t) => sum + t.input + t.output + t.cacheRead + t.cacheCreation, 0);
+}
+/**
+ * `value` with `digits` decimals as Python's `format` writes it. A tie such as 6.5 or 12.25
+ * (exact in binary) goes to the even digit there and to the larger one in `toFixed`.
+ */
+function formatFixed(value, digits) {
+    const rounded = value.toFixed(digits);
+    // `toFixed` writes the exact binary value up to 100 digits: a tie is a 5 and then zeros.
+    const exact = value.toFixed(digits + 30);
+    const tail = exact.slice(exact.length - 30);
+    if (!/^50*$/.test(tail)) {
+        return rounded;
+    }
+    const kept = exact.slice(0, exact.length - 30).replace(/\.$/, "");
+    return Number(rounded.at(-1)) % 2 === 0 ? rounded : kept;
+}
+export function formatTokens(count) {
+    if (count >= 1_000_000) {
+        return `${formatFixed(count / 1_000_000, 1)}M`;
+    }
+    if (count >= 1_000) {
+        return `${formatFixed(count / 1_000, 1)}k`;
+    }
+    return String(count);
+}
+/** The time to a reset, `delta` in milliseconds: minutes, then hours, then days and hours. */
+export function formatUntil(delta) {
+    const minutes = Math.max(0, Math.floor(delta / MINUTE_MS));
+    if (minutes < 60) {
+        return `${minutes}m`;
+    }
+    let hours = Math.floor(minutes / 60);
+    if (hours < 48) {
+        return `${hours}h`;
+    }
+    // Days and hours, as the terminal's weekly reset timer (ccstatusline) counts down a week.
+    const days = Math.floor(hours / 24);
+    hours %= 24;
+    return hours ? `${days}d ${hours}h` : `${days}d`;
+}
+/** `3% ↻ 2h`: the share used, and the time to its reset when known. */
+export function formatLimit(limit, now) {
+    if (limit.resetsAt === null) {
+        return `${limit.percent}%`;
+    }
+    return `${limit.percent}% ↻ ${formatUntil(limit.resetsAt - now)}`;
+}
+/**
+ * The values the footer and `!status` both show, in the footer's order; what is not known is left
+ * out. One list, so the two never write a value differently.
+ */
+export function footerFields(data, now) {
+    const fields = [];
+    if (data.model) {
+        fields.push({ key: "model", label: "Model", value: data.model });
+    }
+    if (data.effort) {
+        fields.push({
+            key: "effort",
+            label: "Effort",
+            value: data.effort,
+            detail: data.effortObserved ?? undefined,
+        });
+    }
+    if (data.branch) {
+        fields.push({ key: "branch", label: "Branch", value: data.branch });
+    }
+    if (data.changes !== null) {
+        fields.push({
+            key: "changes",
+            label: "Uncommitted",
+            value: `(+${data.changes[0]},-${data.changes[1]})`,
+        });
+    }
+    if (data.sessionTokens !== null) {
+        fields.push({
+            key: "tokens",
+            label: "Session tokens",
+            value: formatTokens(data.sessionTokens),
+        });
+    }
+    if (data.contextPercent !== null) {
+        fields.push({
+            key: "context",
+            label: "Context",
+            value: `${formatFixed(data.contextPercent, 0)}%`,
+        });
+    }
+    if (data.sessionLimit) {
+        fields.push({
+            key: "session_limit",
+            label: "5h limit",
+            value: formatLimit(data.sessionLimit, now),
+        });
+    }
+    if (data.weekLimit) {
+        fields.push({ key: "week_limit", label: "7d limit", value: formatLimit(data.weekLimit, now) });
+    }
+    return fields;
+}
+/** `auto (medium)`: a value and what it ran at, or the value alone. */
+export function valueWithDetail(field) {
+    return !field.detail ? field.value : `${field.value} (${field.detail})`;
+}
+/**
+ * The footer's values as `!status` lines, one per field; bypass and the folder are left out,
+ * since the status's Mode and Directory lines already show them.
+ */
+export function formatStatusFields(data, now) {
+    return footerFields(data, now).map((field) => `${field.label}: \`${valueWithDetail(field)}\``);
+}

package/dist/core/guide.js

@@ -0,0 +1,50 @@
+/** `!guide`: the guide assembled from the parts of `texts.ts` that the agent and the chat can serve. */
+import * as texts from "./texts.js";
+import { fill, named } from "./texts.js";
+/** `a`, `a and b`, `a, b and c`. */
+function joined(items) {
+    if (items.length < 2)
+        return items.join("");
+    return `${items.slice(0, -1).join(", ")} and ${items.at(-1)}`;
+}
+/** The guide for these names, with only the parts `offered` says the pair can serve. */
+export function guideText(names, offered) {
+    const say = (text) => typeof text === "string" ? text : named(text, names);
+    const choices = [
+        offered.models ? texts.GUIDE_SETUP_MODEL : null,
+        offered.efforts ? texts.GUIDE_SETUP_EFFORT : null,
+        offered.bypass ? texts.GUIDE_SETUP_BYPASS : null,
+    ].flatMap((item) => (item === null ? [] : [say(item)]));
+    const start = [
+        texts.GUIDE_START,
+        say(offered.folderTrust ? texts.GUIDE_BIND_TRUSTED : texts.GUIDE_BIND_ANY),
+        say(texts.GUIDE_FIRST_MESSAGE),
+        ...(choices.length > 0 ? [fill(texts.GUIDE_SETUP, { choices: joined(choices) })] : []),
+    ];
+    const approvals = [
+        say(texts.GUIDE_PERMISSION),
+        ...(offered.questions ? [say(texts.GUIDE_QUESTION)] : []),
+    ];
+    const sessions = texts.GUIDE_SESSIONS_STATUS +
+        (offered.backgroundTasks ? texts.GUIDE_SESSIONS_TASKS : "") +
+        texts.GUIDE_SESSIONS_STOP +
+        (offered.sessionListing ? ` ${texts.GUIDE_SESSIONS_RESUME}` : "") +
+        ` ${texts.GUIDE_SESSIONS_TERMINAL}`;
+    const [first, ...others] = names.newSession.map((name) => `\`!${name}\``);
+    const newSession = first === undefined
+        ? ""
+        : ` ${fill(texts.GUIDE_NEW_SESSION, { names: others.length > 0 ? `${first} (${others.join(", ")})` : first })}`;
+    const commands = say(texts.GUIDE_COMMANDS) + newSession;
+    const sections = [
+        say(texts.GUIDE_INTRO),
+        start.join("\n"),
+        ...(offered.commands ? [commands] : []),
+        `${offered.questions ? texts.GUIDE_APPROVALS_AND_QUESTIONS : texts.GUIDE_APPROVALS}\n${approvals.join(" ")}`,
+        sessions,
+        ...(offered.fileUpload ? [say(texts.GUIDE_FILES)] : []),
+        ...(offered.bypass ? [say(texts.GUIDE_BYPASS)] : []),
+        ...(offered.updates ? [texts.GUIDE_UPDATES] : []),
+        texts.GUIDE_END,
+    ];
+    return sections.join("\n\n");
+}

package/dist/core/hold.js

@@ -0,0 +1,126 @@
+/**
+ * Questions that hold a message before it is sent. The same-folder hold: before a message wakes
+ * an idle session while a live session of another thread (any channel) is busy in the same
+ * resolved folder, the daemon asks
+ * `Another session is working in this folder: <link>. Send anyway?`, with two buttons,
+ * `Send anyway` and `Don't send`, which the code calls Continue and Cancel.
+ * The session setup (`setup.ts`) is the other one: model, effort and bypass, then Start.
+ *
+ * Kept in memory only, like `Approvals`: a hold never outlives the process (`!stop`, a top-level
+ * `!stop` of its channel, and a drain all cancel one exactly as Cancel does), so nothing here
+ * needs to survive a restart. A thread has at most one open at a time, whichever kind.
+ */
+import { randomBytes } from "node:crypto";
+/**
+ * Questions waiting for the owner, by an id that only the posted buttons carry (as `Approvals`
+ * keys its own requests).
+ */
+export class Holds {
+    entries = new Map();
+    open(channelId, threadId, context = null) {
+        const holdId = randomBytes(16).toString("base64url");
+        let settle = () => { };
+        const answer = new Promise((resolve) => {
+            settle = resolve;
+        });
+        const pending = {
+            channelId,
+            threadId,
+            answer,
+            decided: false,
+            messageTs: null,
+            context,
+            cancelled: false,
+        };
+        this.entries.set(holdId, { pending, settle });
+        return [holdId, pending];
+    }
+    get(holdId) {
+        return this.entries.get(holdId)?.pending ?? null;
+    }
+    /**
+     * Resolve once with `value` (null cancels), and only from the channel and thread the request
+     * was posted in. A value keeps the entry until the asker `discard`s it, so a stop that arrives
+     * while the answer is applied still finds it (`cancel`).
+     */
+    resolve(holdId, channelId, threadId, value) {
+        const entry = this.entries.get(holdId);
+        if (entry === undefined ||
+            entry.pending.channelId !== channelId ||
+            entry.pending.threadId !== threadId ||
+            entry.pending.decided) {
+            return null;
+        }
+        entry.pending.decided = true;
+        entry.settle(value);
+        if (value === null)
+            this.entries.delete(holdId);
+        return entry.pending;
+    }
+    /**
+     * Record the message that shows a hold, so it can be removed once decided; false when the hold
+     * was decided before its message was known (a click or `!stop` while posting).
+     */
+    posted(holdId, messageTs) {
+        const entry = this.entries.get(holdId);
+        if (entry === undefined)
+            return false;
+        entry.pending.messageTs = messageTs;
+        return !entry.pending.decided;
+    }
+    /**
+     * Cancel the hold open in this thread, if any: the same outcome as the owner clicking Cancel
+     * (`!stop`, a top-level `!stop` of its channel, a drain). One already answered but still being
+     * applied is flagged `cancelled` instead: its asker sends nothing.
+     */
+    cancel(channelId, threadId) {
+        for (const [holdId, entry] of [...this.entries]) {
+            const { pending } = entry;
+            if (pending.channelId !== channelId || pending.threadId !== threadId)
+                continue;
+            if (!pending.decided) {
+                pending.decided = true;
+                entry.settle(null);
+                this.entries.delete(holdId);
+                return pending;
+            }
+            if (!pending.cancelled) {
+                pending.cancelled = true;
+                return pending;
+            }
+        }
+        return null;
+    }
+    /**
+     * The id of the open hold shown by this message, for a control that carries no id of its own
+     * (a select): null when it is decided, gone, or shown elsewhere.
+     */
+    atMessage(channelId, threadId, messageTs) {
+        for (const [holdId, { pending }] of this.entries) {
+            if (pending.channelId === channelId &&
+                pending.threadId === threadId &&
+                pending.messageTs === messageTs &&
+                !pending.decided) {
+                return holdId;
+            }
+        }
+        return null;
+    }
+    /**
+     * Whether this message shows a hold that was decided and whose answer is still being applied:
+     * false once its asker discarded it, as for a hold never held (a restart).
+     */
+    decidedAt(channelId, threadId, messageTs) {
+        for (const { pending } of this.entries.values()) {
+            if (pending.channelId === channelId &&
+                pending.threadId === threadId &&
+                pending.messageTs === messageTs) {
+                return pending.decided;
+            }
+        }
+        return false;
+    }
+    discard(holdId) {
+        this.entries.delete(holdId);
+    }
+}

package/dist/core/instance.js

@@ -0,0 +1,46 @@
+/**
+ * The instance: which of the daemons on one machine this is. It is a name, or none for the default
+ * instance, and what is the instance's own derives from it here: its configuration folder and its
+ * scratch folder. The same rule holds on every system, and a function takes the home and the
+ * temporary folder as arguments so that a test passes its own.
+ */
+import { join } from "node:path";
+/**
+ * The variable that selects an instance when `--instance` is absent. The command line reads it;
+ * the daemon writes it to its own environment, so that the sessions it starts inherit it.
+ */
+export const INSTANCE_VARIABLE = "ALLABOARD_INSTANCE";
+export const DEFAULT_INSTANCE = { name: null };
+// 32 characters at most: the lock of a Linux instance is a socket, whose path has 108 bytes on
+// Linux (`sun_path`); macOS, whose limit is 104, takes the directory lock instead.
+const NAME = /^[a-z0-9][a-z0-9-]{0,31}$/;
+/** A name that follows the rule, or the sentence that says why `text` is refused. */
+export function parseInstanceName(text) {
+    if (text === "default") {
+        return {
+            refusal: `the instance name "default" would read as the default instance, which has no name: leave the instance out to use it`,
+        };
+    }
+    if (text === "allaboard") {
+        return {
+            refusal: `the instance name "allaboard" would share the default instance's log, allaboard.log: choose another name`,
+        };
+    }
+    if (!NAME.test(text)) {
+        return {
+            refusal: `${JSON.stringify(text)} is not an instance name: a name is 1 to 32 characters of a-z, 0-9 and "-", and starts with a letter or a digit`,
+        };
+    }
+    return { name: text };
+}
+function suffix(instance) {
+    return instance.name === null ? "" : `-${instance.name}`;
+}
+/** `~/.config/allaboard` for the default instance, `~/.config/allaboard-<name>` for a named one. */
+export function configDirOf(instance, home) {
+    return join(home, ".config", `allaboard${suffix(instance)}`);
+}
+/** The folder under `tmp` that holds the files a chat saves for the instance: `allaboard[-<name>]`. */
+export function scratchDirOf(instance, tmp) {
+    return join(tmp, `allaboard${suffix(instance)}`);
+}