@rse/ase 1.0.7 → 2.0.1

package/dst/ase-task-store-client.js

@@ -0,0 +1,495 @@
+/*
+**  Agentic Software Engineering (ASE)
+**  Copyright (c) 2025-2026 Dr. Ralf S. Engelschall <rse@engelschall.com>
+**  Licensed under Apache 2.0 <https://spdx.org/licenses/Apache-2.0>
+*/
+import path from "node:path";
+import fs from "node:fs";
+import { ofetch } from "ofetch";
+import { Agent } from "undici";
+import { WebSocket } from "ws";
+import { LRUCache } from "lru-cache";
+import { Config } from "./ase-config-core.js";
+import { configSchema } from "./ase-config-schema.js";
+import { parseScope, userStateDir } from "./ase-config-scope.js";
+import * as Delegate from "./ase-task-store-plugin-delegate.js";
+import * as Core from "./ase-task-store-core.js";
+import * as TaskFormat from "./ase-task-format.js";
+/*  the local client: the REST API functionality operating in-process
+    on a built-in storage plugin (the "ase" one in "solo" mode), with the project
+    registered under its configured lifecycle model and task id scheme on every open  */
+export class LocalTaskStoreClient {
+    prjId;
+    lifecycle;
+    idscheme;
+    storage;
+    log;
+    /*  the storage delegates, shared by all concurrently open clients of the
+        same store (keyed by the store only, as the lifecycle model and task
+        id scheme are re-registered on every open and hence survive a switch without a
+        second delegate), so its per-project queue serializes in-process, too  */
+    static shared = new Map();
+    entry;
+    core;
+    constructor(prjId, lifecycle, idscheme, storage, log) {
+        this.prjId = prjId;
+        this.lifecycle = lifecycle;
+        this.idscheme = idscheme;
+        this.storage = storage;
+        this.log = log;
+    }
+    /*  persist a configuration key on scope "project" (which the local store always follows)  */
+    configure(key, value) {
+        const cfg = new Config("config", configSchema, this.log, parseScope("project"));
+        cfg.lock(() => {
+            cfg.read();
+            cfg.set(key, value);
+            cfg.write();
+        });
+    }
+    /*  switch the lifecycle model by persisting "project.task.lifecycle"
+        and re-registering the project (mapping the plan states)  */
+    async setLifecycle(name) {
+        this.configure("project.task.lifecycle", name);
+        this.lifecycle = (await this.core.projectSet(this.prjId, { lifecycle: name })).project.lifecycle;
+    }
+    /*  switch the task id scheme by persisting "project.task.idscheme" and re-registering the project  */
+    async setIdScheme(spec) {
+        this.configure("project.task.idscheme", spec);
+        this.idscheme = (await this.core.projectSet(this.prjId, { idscheme: spec })).project.idscheme;
+    }
+    async missing(op, fallback) {
+        try {
+            return await op();
+        }
+        catch (err) {
+            if (err instanceof Core.Problem && err.status === 404)
+                return fallback;
+            throw err;
+        }
+    }
+    async open() {
+        let entry = LocalTaskStoreClient.shared.get(this.storage.key);
+        if (entry === undefined) {
+            const listeners = new Set();
+            const opened = (async () => {
+                const plugin = await Delegate.loadTaskStoragePlugin(this.storage.plugin, {
+                    options: this.storage.options,
+                    log: (level, message) => this.log.write(level, `task: store: ${message}`)
+                });
+                const store = new Delegate.TaskStore(plugin);
+                const core = new Core.TaskStoreCore(store, (prjId, frame) => {
+                    for (const listener of listeners)
+                        listener(prjId, frame);
+                });
+                await store.open();
+                return { store, core };
+            })();
+            entry = { refs: 0, listeners, opened };
+            LocalTaskStoreClient.shared.set(this.storage.key, entry);
+        }
+        entry.refs++;
+        this.entry = entry;
+        try {
+            this.core = (await entry.opened).core;
+            await this.core.projectSet(this.prjId, { lifecycle: this.lifecycle.name, idscheme: this.idscheme });
+        }
+        catch (err) {
+            await this.close();
+            throw err;
+        }
+    }
+    async close() {
+        const entry = this.entry;
+        if (entry === undefined)
+            return;
+        this.entry = undefined;
+        if (--entry.refs === 0) {
+            if (LocalTaskStoreClient.shared.get(this.storage.key) === entry)
+                LocalTaskStoreClient.shared.delete(this.storage.key);
+            await entry.opened.then((opened) => opened.store.close(), () => { });
+        }
+    }
+    list(fields) {
+        return this.core.taskList(this.prjId, "none", "none", fields ?? "none");
+    }
+    load(id) {
+        return this.missing(() => this.core.taskLoad(this.prjId, id), null);
+    }
+    async save(id, plan, tag, create = false) {
+        return (await this.core.taskSave(this.prjId, id, plan, tag, create)).tag;
+    }
+    newId(title, proposal, taken) {
+        return this.core.taskNewId(this.prjId, { title, proposal, taken });
+    }
+    patch(id, change) {
+        return this.missing(() => this.core.taskPatch(this.prjId, id, change), null);
+    }
+    delete(id) {
+        return this.missing(async () => {
+            await this.core.taskDelete(this.prjId, id);
+            return true;
+        }, false);
+    }
+    purge(age) {
+        return this.core.taskPurge(this.prjId, age);
+    }
+    content(id, index) {
+        return this.missing(() => this.core.attachmentContent(this.prjId, id, String(index)), null);
+    }
+    attach(id, attachment, append = false) {
+        return this.missing(async () => {
+            await this.core.attachmentAdd(this.prjId, id, attachment, append);
+            return true;
+        }, false);
+    }
+    /*  subscribe to the change events of the project, i.e. the changes made
+        in-process plus the ones detected by the storage plugin itself (e.g.
+        by polling a remote storage), keeping the store opened meanwhile and
+        reporting it as connected once opened; returns a function to unsubscribe  */
+    subscribe(onChange, onState) {
+        const listener = (prjId) => {
+            if (prjId === this.prjId)
+                onChange();
+        };
+        let stopped = false;
+        const start = async () => {
+            await this.open();
+            if (stopped)
+                await this.close();
+            else {
+                this.entry?.listeners.add(listener);
+                onState?.(true);
+            }
+        };
+        start().catch((err) => {
+            this.log.write("warning", `task: store: subscription failed: ${err instanceof Error ? err.message : String(err)}`);
+        });
+        return () => {
+            stopped = true;
+            this.entry?.listeners.delete(listener);
+            this.close().catch(() => { });
+        };
+    }
+}
+/*  the interval of the keepalive pings of the event subscription (where a connection without
+    any traffic for this interval is pinged and without any traffic for twice this interval
+    is terminated) and the timeout of its WebSocket handshake  */
+const KEEPALIVE_MS = 15 * 1000;
+const HANDSHAKE_MS = 10 * 1000;
+/*  the remote client: the REST API of a task store server, with the
+    project registered under its configured lifecycle model and task id
+    scheme on first use only (afterwards adopting the lifecycle model and
+    task id scheme of the registered project) and every problem details
+    response raised as an error; an "insecure" client skips the TLS
+    certificate verification  */
+export class RemoteTaskStoreClient {
+    prjId;
+    configured;
+    configuredIdScheme;
+    log;
+    base;
+    token;
+    insecure;
+    /*  the effective lifecycle models and task id schemes of the registered projects
+        (TTL-bounded, to spare consecutive operations the registration round-trips)  */
+    static registered = new LRUCache({ max: 16, ttl: 10 * 1000 });
+    dispatcher;
+    lifecycle;
+    idscheme;
+    constructor(prjId, configured, configuredIdScheme, log, base, token, insecure) {
+        this.prjId = prjId;
+        this.configured = configured;
+        this.configuredIdScheme = configuredIdScheme;
+        this.log = log;
+        this.base = base;
+        this.token = token;
+        this.insecure = insecure;
+        this.lifecycle = configured;
+        this.idscheme = configuredIdScheme;
+        this.dispatcher = insecure ? new Agent({ connect: { rejectUnauthorized: false } }) : undefined;
+    }
+    /*  raise a failed connection as an unreachable store error,
+        reporting the innermost cause (like "connect ECONNREFUSED")  */
+    unreachable(err) {
+        let cause = err;
+        while (cause instanceof Error && cause.cause instanceof Error)
+            cause = cause.cause;
+        const reason = cause instanceof Error ? cause.message : String(cause);
+        throw new Error(`task: store "${this.base}" unreachable: ${reason}`, { cause: err });
+    }
+    /*  perform a request: a 404 response or a tolerated error response yields
+        a null result, any other error response is raised as a problem carrying
+        its status, and a failed connection is raised as an unreachable store error  */
+    async request(method, url, body, headers = {}, tolerated = []) {
+        const r = await ofetch.raw(`${this.base}${url}`, {
+            method,
+            headers: {
+                Authorization: `Bearer ${this.token}`,
+                ...(body !== undefined ? { "Content-Type": "application/json" } : {}),
+                ...headers
+            },
+            body: body !== undefined ? JSON.stringify(body) : undefined,
+            dispatcher: this.dispatcher,
+            signal: AbortSignal.timeout(10000),
+            ignoreResponseError: true
+        }).catch((err) => this.unreachable(err));
+        if (r.status === 404 || tolerated.includes(r.status))
+            return null;
+        if (r.status < 200 || r.status >= 300) {
+            const d = r._data;
+            throw new Core.Problem(r.status, `store "${this.base}": ${d?.detail ?? d?.title ?? `HTTP ${r.status}`}`);
+        }
+        return (r._data ?? {});
+    }
+    get tasks() {
+        return `/projects/${this.prjId}/tasks`;
+    }
+    get key() {
+        return `${this.base}/${this.prjId}`;
+    }
+    /*  adopt the lifecycle model and task id scheme of the registered project
+        (the configured task id scheme for a server predating task id schemes)  */
+    adopt(project) {
+        if (project === null)
+            throw new Core.Problem(404, `store "${this.base}": project "${this.prjId}" not registered`);
+        const lifecycle = TaskFormat.taskLifecycles[project.lifecycle.name];
+        if (lifecycle === undefined)
+            throw new Error(`task: store "${this.base}" uses unknown lifecycle model "${project.lifecycle.name}"`);
+        const idscheme = project.idscheme ?? this.configuredIdScheme;
+        if (TaskFormat.checkIdScheme(idscheme) !== "")
+            throw new Error(`task: store "${this.base}" uses invalid task id scheme "${idscheme}"`);
+        this.lifecycle = lifecycle;
+        this.idscheme = idscheme;
+        RemoteTaskStoreClient.registered.set(this.key, { lifecycle, idscheme });
+    }
+    /*  raise a not registered project (dropping its cached registration)  */
+    unregistered() {
+        RemoteTaskStoreClient.registered.delete(this.key);
+        throw new Core.Problem(404, `store "${this.base}": project "${this.prjId}" not registered`);
+    }
+    /*  pass through a task endpoint result, disambiguating a 404 response
+        (null) into a missing task or a not registered project  */
+    async task(result) {
+        if (result === null && await this.request("GET", `/projects/${this.prjId}`) === null)
+            this.unregistered();
+        return result;
+    }
+    async open() {
+        const cached = RemoteTaskStoreClient.registered.get(this.key);
+        if (cached !== undefined) {
+            this.lifecycle = cached.lifecycle;
+            this.idscheme = cached.idscheme;
+            return;
+        }
+        /*  register the project only if not yet registered (via "If-None-Match: *"), as the
+            lifecycle model and task id scheme of a registered project are shared by all its clients  */
+        const created = await this.request("PUT", `/projects/${this.prjId}`, { lifecycle: this.configured.name, idscheme: this.configuredIdScheme }, { "If-None-Match": "*" }, [412]);
+        this.adopt(created ?? await this.request("GET", `/projects/${this.prjId}`));
+        this.mismatch();
+    }
+    async setLifecycle(name) {
+        this.adopt(await this.request("PUT", `/projects/${this.prjId}`, { lifecycle: name }));
+        this.mismatch();
+    }
+    async setIdScheme(spec) {
+        this.adopt(await this.request("PUT", `/projects/${this.prjId}`, { idscheme: spec }));
+        this.mismatch();
+    }
+    /*  warn about a configured lifecycle model or task id scheme deviating from the
+        one of the registered project, once per deviation only (persisted across processes)  */
+    mismatch() {
+        const file = path.join(userStateDir(), "task-lifecycle.json");
+        let seen = {};
+        try {
+            const data = JSON.parse(fs.readFileSync(file, "utf8"));
+            if (typeof data === "object" && data !== null && !Array.isArray(data))
+                seen = data;
+        }
+        catch {
+            /*  no (valid) state yet  */
+        }
+        const checks = [{
+                key: this.key,
+                config: "project.task.lifecycle",
+                cmd: "lifecycle",
+                configured: this.configured.name,
+                effective: this.lifecycle.name
+            }, {
+                key: `${this.key}#idscheme`,
+                config: "project.task.idscheme",
+                cmd: "idscheme",
+                configured: this.configuredIdScheme,
+                effective: this.idscheme
+            }];
+        let changed = false;
+        for (const check of checks) {
+            const pair = check.effective !== check.configured ?
+                `${check.configured}:${check.effective}` : undefined;
+            if (seen[check.key] === pair)
+                continue;
+            changed = true;
+            if (pair === undefined)
+                seen = Object.fromEntries(Object.entries(seen).filter(([key]) => key !== check.key));
+            else {
+                seen[check.key] = pair;
+                this.log.write("warning", `task: configured "${check.config}" "${check.configured}" ignored, ` +
+                    `as store "${this.base}" uses "${check.effective}" for project "${this.prjId}" ` +
+                    `(align the configuration via "ase config --scope project set ${check.config} ${check.effective}", ` +
+                    `or switch the store via "ase task ${check.cmd} ${check.configured}"; reported once only)`);
+            }
+        }
+        if (!changed)
+            return;
+        try {
+            fs.mkdirSync(path.dirname(file), { recursive: true });
+            fs.writeFileSync(file, JSON.stringify(seen, null, 4) + "\n", "utf8");
+        }
+        catch {
+            /*  best-effort only (the warning then repeats)  */
+        }
+    }
+    async close() {
+        await this.dispatcher?.close();
+    }
+    async list(fields) {
+        const url = this.tasks + (fields !== undefined ? `?fields=${fields}` : "");
+        return (await this.request("GET", url) ?? this.unregistered()).tasks;
+    }
+    async load(id) {
+        return this.task(await this.request("GET", `${this.tasks}/${encodeURIComponent(id)}`));
+    }
+    async save(id, plan, tag, create = false) {
+        const result = await this.request("PUT", `${this.tasks}/${encodeURIComponent(id)}`, plan, {
+            ...(tag !== undefined ? { "If-Match": `"${tag}"` } : {}),
+            ...(create ? { "If-None-Match": "*" } : {})
+        });
+        if (result === null)
+            this.unregistered();
+        return result.tag;
+    }
+    /*  allocate the next free task id on the server, falling back to determining
+        it locally (without any reservation) on a server predating the allocation  */
+    async newId(title, proposal, taken) {
+        const result = await this.request("POST", `/projects/${this.prjId}/newid`, { title, proposal, taken });
+        if (result !== null)
+            return result;
+        const project = await this.request("GET", `/projects/${this.prjId}`) ?? this.unregistered();
+        const spec = project.idscheme ?? this.idscheme;
+        const ids = [...(await this.list()).map((item) => item.id), ...taken];
+        try {
+            return { scheme: spec, id: TaskFormat.nextTaskId(TaskFormat.parseIdScheme(spec), ids, title, proposal, project.seqmark ?? 0) };
+        }
+        catch (err) {
+            throw new Core.Problem(422, err instanceof Error ? err.message : String(err));
+        }
+    }
+    async patch(id, change) {
+        return this.task(await this.request("PATCH", `${this.tasks}/${encodeURIComponent(id)}`, change));
+    }
+    async delete(id) {
+        return await this.task(await this.request("DELETE", `${this.tasks}/${encodeURIComponent(id)}`)) !== null;
+    }
+    async purge(age) {
+        const result = await this.request("DELETE", `${this.tasks}?age=${encodeURIComponent(age)}`);
+        return (result ?? this.unregistered()).purged;
+    }
+    async attach(id, attachment, append = false) {
+        return await this.task(await this.request("POST", `${this.tasks}/${encodeURIComponent(id)}/attachment${append ? "?append=true" : ""}`, attachment)) !== null;
+    }
+    async content(id, index) {
+        const r = await ofetch.raw(`${this.base}${this.tasks}/${encodeURIComponent(id)}/attachment/${index}/content`, {
+            headers: { Authorization: `Bearer ${this.token}` },
+            responseType: "arrayBuffer",
+            dispatcher: this.dispatcher,
+            signal: AbortSignal.timeout(10000),
+            ignoreResponseError: true
+        }).catch((err) => this.unreachable(err));
+        if (r.status === 404)
+            return this.task(null);
+        if (r.status < 200 || r.status >= 300)
+            throw new Core.Problem(r.status, `store "${this.base}": HTTP ${r.status}`);
+        return { type: r.headers.get("content-type") ?? "application/octet-stream", content: Buffer.from(r._data ?? new ArrayBuffer(0)) };
+    }
+    /*  subscribe to the change events of the project via the WebSocket event
+        endpoint, reconnecting after a connection loss, a failed or timed out
+        handshake, or a connection without any traffic despite keepalive pings
+        (e.g. a half-open one after a network partition), with a change notification
+        on reconnect (as events may have been missed, incl. lifecycle model changes),
+        reporting each change of the connection state (initially disconnected);
+        returns a function to unsubscribe  */
+    subscribe(onChange, onState) {
+        const url = `${this.base.replace(/^http/, "ws")}/projects/${this.prjId}/events`;
+        let ws = null;
+        let timer = null;
+        let stopped = false;
+        let failed = false;
+        const connect = () => {
+            const sock = new WebSocket(url, {
+                headers: { Authorization: `Bearer ${this.token}` },
+                rejectUnauthorized: !this.insecure,
+                handshakeTimeout: HANDSHAKE_MS
+            });
+            ws = sock;
+            /*  keep the connection alive: record any traffic (the frames, and the pings
+                of the task store and the pongs of our own pings), and terminate the
+                connection if there was none since the previous (then unanswered) ping  */
+            let traffic = true;
+            let watchdog = null;
+            const alive = () => { traffic = true; };
+            sock.on("ping", alive);
+            sock.on("pong", alive);
+            sock.on("open", () => {
+                watchdog = setInterval(() => {
+                    if (!traffic) {
+                        this.log.write("debug", `task: store "${this.base}": events: connection unresponsive -- reconnecting`);
+                        sock.terminate();
+                        return;
+                    }
+                    traffic = false;
+                    sock.ping();
+                }, KEEPALIVE_MS);
+                if (failed) {
+                    RemoteTaskStoreClient.registered.delete(this.key);
+                    onChange();
+                }
+                failed = false;
+                onState?.(true);
+            });
+            sock.on("message", (data) => {
+                traffic = true;
+                /*  drop the cached registration on a lifecycle model or task id scheme change  */
+                try {
+                    const frame = JSON.parse(String(data));
+                    if (frame.lifecycle !== undefined || frame.idscheme !== undefined)
+                        RemoteTaskStoreClient.registered.delete(this.key);
+                }
+                catch {
+                    /*  ignore malformed frames (the change is notified anyway)  */
+                }
+                onChange();
+            });
+            sock.on("error", (err) => {
+                this.log.write("debug", `task: store "${this.base}": events: ${err.message}`);
+            });
+            sock.on("close", () => {
+                if (watchdog !== null)
+                    clearInterval(watchdog);
+                ws = null;
+                failed = true;
+                if (!stopped) {
+                    onState?.(false);
+                    timer = setTimeout(connect, 2000);
+                }
+            });
+        };
+        connect();
+        return () => {
+            stopped = true;
+            if (timer !== null)
+                clearTimeout(timer);
+            ws?.close();
+            this.close().catch(() => { });
+        };
+    }
+}