allaboard 0.0.0-stage → 0.4.0

package/dist/core/sessions/tasks.js

@@ -0,0 +1,266 @@
+/**
+ * The primitives of the sessions: a task that can be cancelled, an event, a semaphore, a lock, a
+ * queue, and a wait that a signal ends. The rule they serve is the header of `session.ts`.
+ *
+ * A promise callback runs at the next `await` of the code that made it ready, whether or not
+ * that `await` waits for anything. So a new task starts, and the waiters of an event wake, on
+ * the next turn of the event loop (`setImmediate`), in the order they became ready: the code
+ * that made them ready reaches its own next real wait first.
+ */
+import { getLogger } from "../../log.js";
+import { errorName } from "../../values.js";
+export const logger = getLogger("allaboard.core.sessions.tasks");
+// A stack frame as V8 writes it: `at name (place:line:column)` or `at place:line:column`.
+const FRAME = /^\s+at (?:.+ \()?[^\s()]+:\d+:\d+\)?$/;
+/**
+ * Where an error was thrown, as a log line may say it: the first frame of its stack. The stack
+ * opens with the error's own words, which may run over several lines and may hold one that reads
+ * like a frame, so only what follows them is looked at, and only a line shaped as a frame.
+ */
+function thrownAt(error) {
+    if (!(error instanceof Error) || typeof error.stack !== "string")
+        return "";
+    const words = error.stack.indexOf(error.message);
+    if (words === -1)
+        return "";
+    const frames = error.stack.slice(words + error.message.length).split("\n");
+    const frame = frames.find((line) => FRAME.test(line));
+    return frame === undefined ? "" : ` (${frame.trim()})`;
+}
+/** Resolves on the next turn of the event loop, after every promise callback that is ready. */
+function nextTurn() {
+    return new Promise((resolve) => {
+        setImmediate(resolve);
+    });
+}
+/** What a wait rejects with when its signal aborts. */
+export class Cancelled extends Error {
+    constructor() {
+        super("cancelled");
+        this.name = "Cancelled";
+    }
+}
+/**
+ * `promise`, for a caller that may stop waiting: rejects with the signal's reason when it aborts
+ * first. The promise itself goes on: what it began runs to its end.
+ */
+export function cancellable(promise, signal) {
+    if (signal === undefined)
+        return promise;
+    return new Promise((resolve, reject) => {
+        const onAbort = () => reject(signal.reason);
+        if (signal.aborted) {
+            // Whoever began it still owns its outcome: no unhandled rejection from this side.
+            promise.catch(() => { });
+            onAbort();
+            return;
+        }
+        signal.addEventListener("abort", onAbort, { once: true });
+        promise.then((value) => {
+            signal.removeEventListener("abort", onAbort);
+            resolve(value);
+        }, (error) => {
+            signal.removeEventListener("abort", onAbort);
+            reject(error);
+        });
+    });
+}
+/**
+ * A task. The function starts on the next turn of the event loop, never inside the call that
+ * made the task, and the sessions set state right after creating one. A task cancelled before
+ * it started never runs. With `immediate`, the function has started running when the task is
+ * made, which is the rule of the chat provider's passes (the header of `sinks.ts`).
+ * `cancel` aborts the task's signal with `Cancelled`; the function decides which of its waits
+ * take it. A task that fails rejects `result()` and never surfaces as an unhandled rejection.
+ * When nobody has asked for its result, the failure is logged by its name and by where it was
+ * thrown, so that a task that broke leaves a trace.
+ */
+export class Task {
+    controller = new AbortController();
+    promise;
+    finished = false;
+    retrieved = false;
+    constructor(run, options = {}) {
+        this.promise = this.start(run, options.immediate === true);
+        this.promise.catch((error) => {
+            if (this.retrieved || error instanceof Cancelled)
+                return;
+            logger.error(`a task failed: ${errorName(error)}${thrownAt(error)}`);
+        });
+    }
+    async start(run, immediate) {
+        try {
+            if (!immediate) {
+                await nextTurn();
+                this.controller.signal.throwIfAborted();
+            }
+            return await run(this.controller.signal);
+        }
+        finally {
+            this.finished = true;
+        }
+    }
+    get signal() {
+        return this.controller.signal;
+    }
+    /** Whether the function has returned or thrown. */
+    get done() {
+        return this.finished;
+    }
+    cancel() {
+        if (!this.finished && !this.controller.signal.aborted)
+            this.controller.abort(new Cancelled());
+    }
+    /** The function's own outcome: whoever asks for it answers for its failure. */
+    result() {
+        this.retrieved = true;
+        return this.promise;
+    }
+    /** Resolves when the task ends, however it ends: awaiting a task one has just cancelled. */
+    settled() {
+        return this.promise.then(() => { }, () => { });
+    }
+}
+/**
+ * An event. `set` wakes its waiters on the next turn of the event loop: whoever set it goes on
+ * to its own next real wait first, so a waiter never sees the state of the setter half-way
+ * through what it was doing. A waiter whose signal aborts leaves and rejects with the signal's
+ * reason.
+ */
+export class Event {
+    value = false;
+    waiters = new Set();
+    get isSet() {
+        return this.value;
+    }
+    set() {
+        this.value = true;
+        if (this.waiters.size === 0)
+            return;
+        const waiting = [...this.waiters];
+        this.waiters.clear();
+        setImmediate(() => {
+            for (const wake of waiting)
+                wake();
+        });
+    }
+    clear() {
+        this.value = false;
+    }
+    wait(signal) {
+        if (signal?.aborted)
+            return Promise.reject(signal.reason);
+        if (this.value)
+            return Promise.resolve();
+        return new Promise((resolve, reject) => {
+            const wake = () => {
+                signal?.removeEventListener("abort", onAbort);
+                resolve();
+            };
+            const onAbort = () => {
+                this.waiters.delete(wake);
+                reject(signal?.reason);
+            };
+            signal?.addEventListener("abort", onAbort, { once: true });
+            this.waiters.add(wake);
+        });
+    }
+}
+/**
+ * A counting gate: at most `limit` holders at once, the others served in the order they
+ * came. A place given back goes straight to the first in line, so it is never free for a
+ * newcomer to take ahead of a waiter.
+ */
+export class Semaphore {
+    free;
+    waiters = [];
+    constructor(limit) {
+        this.free = limit;
+    }
+    /**
+     * Resolves with the function that gives the place back, once it is this caller's turn; calling
+     * that function twice gives back one place. A waiter whose signal aborts leaves the line and
+     * rejects with the signal's reason.
+     */
+    acquire(signal) {
+        if (signal?.aborted)
+            return Promise.reject(signal.reason);
+        if (this.free > 0) {
+            this.free -= 1;
+            return Promise.resolve(this.releaser());
+        }
+        return new Promise((resolve, reject) => {
+            const turn = () => {
+                signal?.removeEventListener("abort", onAbort);
+                resolve(this.releaser());
+            };
+            const onAbort = () => {
+                const index = this.waiters.indexOf(turn);
+                if (index !== -1)
+                    this.waiters.splice(index, 1);
+                reject(signal?.reason);
+            };
+            signal?.addEventListener("abort", onAbort, { once: true });
+            this.waiters.push(turn);
+        });
+    }
+    releaser() {
+        let released = false;
+        return () => {
+            if (released)
+                return;
+            released = true;
+            const next = this.waiters.shift();
+            if (next === undefined)
+                this.free += 1;
+            else
+                next();
+        };
+    }
+    /** `work` while holding a place, given back however `work` ends. */
+    async run(work, signal) {
+        const release = await this.acquire(signal);
+        try {
+            return await work();
+        }
+        finally {
+            release();
+        }
+    }
+}
+/** A lock: a semaphore of one place. */
+export class Mutex extends Semaphore {
+    constructor() {
+        super(1);
+    }
+}
+/** A queue, unbounded, for one consumer. */
+export class Queue {
+    items = [];
+    filled = new Event();
+    get size() {
+        return this.items.length;
+    }
+    get empty() {
+        return this.items.length === 0;
+    }
+    putNowait(item) {
+        this.items.push(item);
+        this.filled.set();
+    }
+    /** The next item now; throws on an empty queue, as `get_nowait` raised. */
+    getNowait() {
+        const item = this.items.shift();
+        if (item === undefined)
+            throw new RangeError("the queue is empty");
+        if (this.items.length === 0)
+            this.filled.clear();
+        return item;
+    }
+    /** The next item, waiting for one; the wait leaves through its signal. */
+    async get(signal) {
+        while (this.items.length === 0)
+            await this.filled.wait(signal);
+        return this.getNowait();
+    }
+}

package/dist/core/sessions/turn.js

@@ -0,0 +1,45 @@
+/** One prompt and its reply, the turn that is running, and the notes about prompts that never ran. */
+import { randomUUID } from "node:crypto";
+import { blank } from "../../text.js";
+import { oneLine } from "../reply/words.js";
+import * as texts from "../texts.js";
+import { ASKED_LIMIT, NOT_SENT_START } from "./constants.js";
+import { Event } from "./tasks.js";
+export class Turn {
+    prompt;
+    sink;
+    done = new Event();
+    /** The daemon's own id for the prompt, which the agent names when it takes it. */
+    uuid = randomUUID();
+    constructor(prompt, sink) {
+        this.prompt = prompt;
+        this.sink = sink;
+    }
+}
+/** The owner's question on one line, as a note about a message that was not sent quotes it. */
+export function asked(prompt) {
+    const text = typeof prompt === "string"
+        ? prompt
+        : prompt
+            .filter((part) => part.type === "text")
+            .map((part) => part.text)
+            .join(" ");
+    return blank(text) ? texts.PROMPT_IMAGE : oneLine(text, ASKED_LIMIT);
+}
+/**
+ * The note that names turns that will never be sent: how many, why, and the start of each, so
+ * the owner knows which to send again.
+ */
+export function notSent(turns, because) {
+    const header = texts.fill(turns.length === 1 ? texts.NOT_SENT_ONE : texts.NOT_SENT_MANY, {
+        count: turns.length,
+        because,
+    });
+    const starts = turns.map((turn) => `- "${oneLine(asked(turn.prompt), NOT_SENT_START)}"`);
+    return [header, ...starts].join("\n");
+}
+/** The note for the reply a turn that took `count` prompts into itself ends with. */
+export function takenNote(count, names) {
+    const note = count === 1 ? texts.TAKEN_INTO_REPLY_ONE : texts.TAKEN_INTO_REPLY_MANY;
+    return texts.fill(texts.named(note, names), { count });
+}

package/dist/core/setup.js

@@ -0,0 +1,28 @@
+export const DEFAULT = "default";
+export const DEFAULT_CHOICE = { model: DEFAULT, effort: DEFAULT, bypass: false };
+/** The levels `model` accepts, in the agent's order; empty for a model without effort. */
+export function effortLevels(models, model) {
+    const entry = models.find((m) => m.value === model && m.supportsEffort);
+    return entry === undefined ? [] : entry.supportedEffortLevels;
+}
+/**
+ * The owner's choice from a selection. A model the agent did not list reads as its default; an
+ * effort the chosen model does not support reads as `Default`, which is what the message shows
+ * after a model change.
+ */
+export function choiceOf(models, selection) {
+    const listed = selection.model === DEFAULT || models.some((m) => m.value === selection.model);
+    const model = listed ? selection.model : DEFAULT;
+    const effort = effortLevels(models, model).includes(selection.effort)
+        ? selection.effort
+        : DEFAULT;
+    return { model, effort, bypass: selection.bypass };
+}
+export function summaryOf(models, choice) {
+    const listed = models.find((m) => m.value === choice.model);
+    return {
+        model: listed === undefined ? choice.model : listed.displayName,
+        effort: choice.effort === DEFAULT ? null : choice.effort,
+        bypass: choice.bypass,
+    };
+}