allaboard 0.0.0-stage → 0.4.0

package/dist/core/reply/tail.js

@@ -0,0 +1,24 @@
+/**
+ * Where a thread's list of what still runs is drawn. A pure function of the order of the
+ * messages, so a provider can ask it again after every change. The footer is not placed here: the
+ * session decides it, once, and a provider draws it under the app's last message.
+ */
+/**
+ * For each entry, what it shows: the list goes to the lowest reply of the thread once it rests,
+ * and to no reply while that one is still written. Left on a reply above it, the list sat
+ * between that reply and the one being written, then jumped below it (seen on Slack desktop,
+ * 2026-10-15).
+ */
+export function tails(entries) {
+    const lowest = entries.reduce((found, entry) => (found === undefined || entry.at > found.at ? entry : found), undefined);
+    const holder = lowest?.resting ? lowest : undefined;
+    return new Map(entries.map((entry) => [entry.key, { running: entry === holder }]));
+}
+/** Nothing of the owner's and no other reply sits below `at`. */
+export function isLast(at, others, ownerMarks) {
+    return others.every((other) => other < at) && ownerMarks.every((mark) => mark < at);
+}
+/** Another reply has a message below `at`. */
+export function isOvertaken(at, others) {
+    return others.some((other) => other > at);
+}

package/dist/core/reply/words.js

@@ -0,0 +1,32 @@
+/** The words a reply's lines share, whoever writes them: the renderer, the fold, a chat provider. */
+import { escaped, PY_SPACE } from "../../text.js";
+export const BACKGROUND = "Running in background";
+export const STOPPED = "Stopped";
+// The most of a title one line shows, a call's in a reply or a session's in a list.
+export const TITLE_LIMIT = 80;
+const SPACES = new RegExp(`[${PY_SPACE}]+`);
+/** `value` with its runs of whitespace as one space and none at its ends: `" ".join(value.split())`. */
+export function spaced(value) {
+    return value
+        .split(SPACES)
+        .filter((word) => word !== "")
+        .join(" ");
+}
+// The line boundaries of Python's `str.splitlines`: more than `\n` and `\r`, and not the unit
+// separator U+001F, which is whitespace and no boundary.
+const LINE_END_CODES = [0x0a, 0x0b, 0x0c, 0x0d, 0x1c, 0x1d, 0x1e, 0x85, 0x2028, 0x2029];
+const LINE_ENDS = new RegExp(`\\r\\n|[${LINE_END_CODES.map(escaped).join("")}]`);
+/** The lines of `text` as Python's `str.splitlines()` cuts them: a boundary at the end adds none. */
+export function splitLines(text) {
+    const lines = text.split(LINE_ENDS);
+    if (lines.at(-1) === "")
+        lines.pop();
+    return lines;
+}
+/** `value` on one line, its runs of whitespace as one space, cut with `…` past `limit` characters. */
+export function oneLine(value, limit) {
+    const text = spaced(value);
+    // Counted in code points: an emoji is one character.
+    const chars = Array.from(text);
+    return chars.length <= limit ? text : `${chars.slice(0, limit - 1).join("")}…`;
+}

package/dist/core/requests.js

@@ -0,0 +1,158 @@
+/**
+ * The agent's permission requests and questions waiting for the owner. This is the bookkeeping
+ * that belongs to no chat provider: which request is pending, who may resolve it, and what the
+ * answer is. A provider draws the request and reports what the owner chose.
+ *
+ * Kept in memory only: a request never outlives the process. The wait is a promise the agent
+ * side holds (`Pending.decision`), settled by `resolve` or `denyAll` and by nothing else.
+ */
+import { randomBytes } from "node:crypto";
+import { DENY_MESSAGE, named, SKIP_MESSAGE } from "./texts.js";
+export const APPROVE = { kind: "approve" };
+export const DENY = { kind: "deny" };
+/**
+ * The answer the agent takes for what the owner chose. A refusal is a dismissal when the request
+ * was a question (`questions` is not null), so Claude is told the form was skipped, not denied.
+ */
+export function toAnswer(outcome, questions, names) {
+    switch (outcome.kind) {
+        case "answer":
+            return { answered: true, answers: outcome.answers, notes: outcome.notes };
+        case "approve":
+            return { allow: true };
+        case "deny":
+            return questions !== null && questions.length > 0
+                ? { answered: false, message: SKIP_MESSAGE }
+                : { allow: false, message: named(DENY_MESSAGE, names) };
+    }
+}
+/**
+ * A question's answer as Claude Code takes it: the labels of the options picked and the text
+ * typed under Other, which is the answer itself (tools reference); null when there is neither.
+ * `picked` are indexes into `question.options`; one that names no option throws, since the
+ * form only offers the options the question has.
+ */
+export function answerOf(question, picked, typed) {
+    let labels = picked.map((index) => {
+        const option = question.options[index];
+        if (option === undefined)
+            throw new RangeError(`no option ${index} in the question`);
+        return option.label;
+    });
+    if (typed)
+        labels = question.multiSelect ? [...labels, typed] : [typed];
+    if (labels.length === 0)
+        return null;
+    return question.multiSelect ? labels : labels[0];
+}
+/** Requests waiting for the owner, by an id that only the posted buttons carry. */
+export class Approvals {
+    entries = new Map();
+    names;
+    /** `names` fill the message a denial carries to the agent. */
+    constructor(names) {
+        this.names = names;
+    }
+    /** Starts waiting for `title`'s request; `questions` makes it a question. */
+    open(channelId, threadId, title, questions = null) {
+        const approvalId = randomBytes(16).toString("base64url");
+        let settle = () => { };
+        const decision = new Promise((resolve) => {
+            settle = resolve;
+        });
+        const pending = {
+            channelId,
+            threadId,
+            title,
+            questions,
+            decision,
+            decided: false,
+            messageTs: null,
+        };
+        this.entries.set(approvalId, { pending, settle });
+        return [approvalId, pending];
+    }
+    get(approvalId) {
+        return this.entries.get(approvalId)?.pending ?? null;
+    }
+    /**
+     * The questions of the request `approvalId`, read from the thread it was posted in; null when
+     * the request is gone, belongs to another thread or has no questions.
+     */
+    questions(approvalId, channelId, threadId) {
+        const pending = this.get(approvalId);
+        if (pending === null ||
+            pending.channelId !== channelId ||
+            pending.threadId !== threadId ||
+            pending.questions === null ||
+            pending.questions.length === 0) {
+            return null;
+        }
+        return pending.questions;
+    }
+    /** Resolve once, and only from the channel and thread the request was posted in. */
+    resolve(approvalId, channelId, threadId, outcome) {
+        const entry = this.entries.get(approvalId);
+        if (entry === undefined ||
+            entry.pending.channelId !== channelId ||
+            entry.pending.threadId !== threadId ||
+            entry.pending.decided) {
+            return null;
+        }
+        this.decide(approvalId, entry, outcome);
+        return entry.pending;
+    }
+    /**
+     * Refuses the one request `approvalId` still open, for an agent that no longer waits for its
+     * answer; null when it was answered or removed already.
+     */
+    giveUp(approvalId) {
+        const entry = this.entries.get(approvalId);
+        if (entry === undefined || entry.pending.decided)
+            return null;
+        this.decide(approvalId, entry, DENY);
+        return entry.pending;
+    }
+    /** Denies every request still open in this thread, and returns them. */
+    denyAll(channelId, threadId) {
+        const denied = [];
+        for (const [approvalId, entry] of [...this.entries]) {
+            const { pending } = entry;
+            if (pending.channelId === channelId && pending.threadId === threadId && !pending.decided) {
+                this.decide(approvalId, entry, DENY);
+                denied.push(pending);
+            }
+        }
+        return denied;
+    }
+    /**
+     * A read-only snapshot of this thread's open requests, for a caller that needs to know which
+     * messages are still live without resolving them: `ThreadSession.close` captures these before
+     * cancelling its reader, since `denyAll`'s own list is empty by the time close reaches it
+     * (issue #19 fix round item 8).
+     */
+    pendingIn(channelId, threadId) {
+        return [...this.entries.values()]
+            .map((entry) => entry.pending)
+            .filter((pending) => pending.channelId === channelId && pending.threadId === threadId);
+    }
+    /**
+     * Record the message that shows a request, so it can be removed once decided; false when the
+     * request was decided before its message was known (`!stop` while posting).
+     */
+    posted(approvalId, messageTs) {
+        const entry = this.entries.get(approvalId);
+        if (entry === undefined)
+            return false;
+        entry.pending.messageTs = messageTs;
+        return true;
+    }
+    discard(approvalId) {
+        this.entries.delete(approvalId);
+    }
+    decide(approvalId, entry, outcome) {
+        entry.pending.decided = true;
+        entry.settle(toAnswer(outcome, entry.pending.questions, this.names));
+        this.entries.delete(approvalId);
+    }
+}

package/dist/core/sessions/constants.js

@@ -0,0 +1,61 @@
+import { Named } from "../texts.js";
+// The events that belong to a turn: the first one that arrives with no turn running starts one
+// (a stream event, an assistant or a user message, a result).
+export const TURN_EVENTS = new Set([
+    "message_started",
+    "message_ended",
+    "text_started",
+    "text_delta",
+    "text",
+    "call_started",
+    "call_ended",
+    "agent_error",
+    "turn_ended",
+]);
+export const TASK_EVENTS = new Set([
+    "task_started",
+    "task_progress",
+    "task_ended",
+    "task_updated",
+]);
+// After a background task's notification, the CLI starts a turn of its own to report it
+// (measured on Claude Code 2.1.280). If that turn never comes, the owner's queue moves on.
+export const INJECTED_TURN_WAIT = 30.0;
+// How long the answer to `!stop` waits for the reply it cut short to end. An interrupted turn
+// ends within a second or two; a final write that is retried takes ten.
+export const STOP_TAIL_WAIT = 15.0;
+// Each kind of task as the list of what still runs counts it and as its end line names it, the way the terminal
+// prints `Agent "..." finished`. The agent decides which kind a task is (`task_started.kind`): a
+// kind it does not name arrives as `other`, which counts and reads as a task, so a new one shows
+// with no change.
+export const TASK_WORDS = {
+    command: ["shell", "Background command"],
+    subagent: ["agent", "Agent"],
+    other: ["task", "Task"],
+};
+// Tasks whose kind and description the session keeps. A task can end with a terminal
+// `task_updated` and no notification (SDK docstring), so past this many the oldest are dropped.
+export const TASKS_KEPT = 200;
+// The kinds whose notification summary is already the terminal's end line (measured: a
+// command's reads `Background command "..." completed (exit code 0)`; an agent's is its result).
+export const SUMMARY_IS_END_LINE = new Set(["command"]);
+// How much of the reason an agent failed its end line keeps: the terminal prints it whole, and
+// the longest one captured (a refused request, with its gateway and model) ran to 330 characters.
+export const FAILURE_LIMIT = 400;
+// Tasks whose reply the session remembers. An ended task stays a while, since an agent can
+// report again after its notification; past this many, the oldest ended ones are forgotten.
+export const TASK_REPLIES_KEPT = 100;
+// How often a stopping daemon checks whether every channel's turns have ended.
+export const DRAIN_POLL_SECONDS = 0.5;
+// A session's agent process closes after this long with nothing to do (idle, and no approval,
+// question or background report pending); the next message rebuilds it and resumes.
+export const IDLE_CLOSE_SECONDS = 3600.0;
+// The one hold a thread can have open at once, in the session's waiting set alongside real
+// approval ids (`waitingForOwner` and the idle-close timer treat every entry the same).
+export const HOLD_MARKER = "d8-hold";
+// How much of the owner's question a note about a message that was not sent quotes.
+export const ASKED_LIMIT = 100;
+// How much of each message a note about messages that were not sent quotes.
+export const NOT_SENT_START = 60;
+// What the reader says ended the stream when the back end gave no reason of its own.
+export const PROCESS_EXITED = new Named("the {agent} process exited");

package/dist/core/sessions/deps.js

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

package/dist/core/sessions/directory.js

@@ -0,0 +1,86 @@
+/** Whether a folder can hold a session, the folder a typed path names, and `!status`'s terminal line. */
+import { realpathSync, statSync } from "node:fs";
+import { opendir, stat } from "node:fs/promises";
+import { isAbsolute, sep } from "node:path";
+import { shellQuote } from "../../text.js";
+import { errorCode } from "../../values.js";
+import { ABSENT, expandUser, resolvePath } from "../paths.js";
+import * as texts from "../texts.js";
+import { DirectoryMissing, DirectoryUnreadable, DirectoryUntrusted } from "./errors.js";
+/**
+ * `agent`'s record of trust as `checkDirectory` and the folder list read it. An agent that
+ * keeps none (`folderTrust`) has no gate to start a session behind: every folder counts.
+ */
+export function trustedBy(agent) {
+    return async (folder) => !agent.capabilities.folderTrust || agent.folderTrusted(folder);
+}
+/**
+ * `agent`'s answer for the repository holding a folder when the daemon's own git may run in it:
+ * the one lookup behind the footer and `!open`. Null for an agent with no record of trust
+ * (`folderTrust`): the daemon's git runs in no folder then.
+ */
+export function repositoryBy(agent) {
+    return async (folder) => agent.capabilities.folderTrust ? agent.trustedRepository(folder) : null;
+}
+/**
+ * Rejects with the `DirectoryUnavailable` that keeps a session from starting in `directory`,
+ * the first found in the order the owner can act on: missing, unreadable, untrusted.
+ */
+export async function checkDirectory(directory, trusted, names) {
+    // One stat and one directory open on a local folder, as a session start always made them.
+    // A folder the daemon is not let into is unreadable at either: at the stat when a folder
+    // above it is closed, at the open when it is closed itself. Both say `DirectoryUnreadable`.
+    try {
+        if (!(await stat(directory)).isDirectory())
+            throw new DirectoryMissing(directory);
+        await (await opendir(directory)).close();
+    }
+    catch (error) {
+        const code = errorCode(error);
+        if (code === "EACCES" || code === "EPERM")
+            throw new DirectoryUnreadable(directory);
+        // A path with a null in it is one Node refuses to look at: it names no folder.
+        if (code !== undefined && (ABSENT.has(code) || code === "ERR_INVALID_ARG_VALUE")) {
+            throw new DirectoryMissing(directory);
+        }
+        throw error;
+    }
+    if (!(await trusted(directory)))
+        throw new DirectoryUntrusted(directory, names);
+}
+/** Whether `path` is `root` or lies under it. */
+function under(path, root) {
+    return path === root || path.startsWith(root.endsWith(sep) ? root : root + sep);
+}
+/** The real directory `raw` names, if it exists under `root`; guards against a typo only. */
+export function resolveDirectory(raw, root) {
+    // A relative path is read under the root: the daemon's own working directory means nothing
+    // to the owner (launchd starts it in `/`).
+    const written = expandUser(raw);
+    try {
+        // Joined as text: the disk follows a link before a `..`.
+        const path = resolvePath(isAbsolute(written) ? written : `${root}/${written}`);
+        if (!statSync(path).isDirectory() || !under(path, root))
+            return null;
+        // The kernel is asked too, since a session runs in the folder it reaches: whatever the
+        // reading above made of the spelling, that folder lies under the root or is refused.
+        return under(realpathSync.native(path), realpathSync.native(root)) ? path : null;
+    }
+    catch {
+        return null; // it names nothing, or goes through a loop of links
+    }
+}
+/**
+ * The `!status` line with the command that forks a session in the terminal (the agent's
+ * `words.terminal`, `template`), run from the thread's folder, where `!resume` in its channel
+ * then finds the fork. `escapeMarkup` is the chat's, for a reference (`ChatProvider.escape`).
+ */
+export function terminalLine(template, directory, sessionId, escapeMarkup) {
+    const command = texts.fill(template, {
+        directory: shellQuote(directory),
+        session: sessionId,
+    });
+    // A code span cannot hold a backtick: such a command is plain text, escaped.
+    const shown = command.includes("`") ? escapeMarkup(command) : `\`${command}\``;
+    return texts.fill(texts.STATUS_TERMINAL, { command: shown });
+}

package/dist/core/sessions/errors.js

@@ -0,0 +1,79 @@
+/** Why a session cannot start, or stopped under whoever was using it. */
+import * as texts from "../texts.js";
+/** The channel's directory cannot be used; `message` tells the owner what to do. */
+export class DirectoryUnavailable extends Error {
+    directory;
+    constructor(directory, message) {
+        super(message);
+        this.name = "DirectoryUnavailable";
+        this.directory = directory;
+    }
+}
+export class DirectoryMissing extends DirectoryUnavailable {
+    constructor(directory) {
+        super(directory, texts.fill(texts.DIRECTORY_MISSING, { directory }));
+        this.name = "DirectoryMissing";
+    }
+}
+/**
+ * The owner has not trusted the folder in the agent: a session would run its hooks and apply
+ * its settings with no trust dialog.
+ */
+export class DirectoryUntrusted extends DirectoryUnavailable {
+    constructor(directory, names) {
+        super(directory, texts.fill(texts.named(texts.DIRECTORY_UNTRUSTED, names), { directory }));
+        this.name = "DirectoryUntrusted";
+    }
+}
+/**
+ * macOS privacy protection (TCC) denies the daemon a folder such as ~/Documents: a process
+ * started by launchd does not inherit the Terminal's permission, and the CLI fails to start.
+ */
+export class DirectoryUnreadable extends DirectoryUnavailable {
+    constructor(directory) {
+        super(directory, texts.fill(texts.DIRECTORY_UNREADABLE, { directory }));
+        this.name = "DirectoryUnreadable";
+    }
+}
+/**
+ * The session closed (the daemon stopping, or the idle close, most likely) while something was
+ * using it: a daemon word (`!status`, `!bypass`), or `submit` queuing an owner's prompt (the
+ * caller retries once, against a freshly looked-up session).
+ */
+export class SessionClosed extends Error {
+    constructor() {
+        super(texts.SESSION_CLOSED);
+        this.name = "SessionClosed";
+    }
+}
+/**
+ * A thread's stored session id could not be resumed: its entry was removed, and the thread
+ * needs a new top-level message to start again.
+ */
+export class SessionGone extends Error {
+    constructor(names, options) {
+        super(texts.named(texts.SESSION_GONE, names), options);
+        this.name = "SessionGone";
+    }
+}
+/**
+ * `!bypass` was asked of an agent with no mode that skips permission requests: nothing was
+ * switched or stored.
+ */
+export class BypassUnavailable extends Error {
+    constructor() {
+        super("the agent has no bypass mode");
+        this.name = "BypassUnavailable";
+    }
+}
+/**
+ * An install is replacing allaboard's own copy (issue #361): no agent process starts until it ends,
+ * since a new one would run the new copy's agent under the old code, or a half-written copy. A
+ * session already connected is not touched.
+ */
+export class StartsBlocked extends Error {
+    constructor() {
+        super(texts.RESTARTING);
+        this.name = "StartsBlocked";
+    }
+}