@rse/ase 1.0.7 → 2.0.0

package/dst/ase-agent-relay-core.js

@@ -0,0 +1,213 @@
+/*
+**  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 * as v from "valibot";
+import * as Core from "./ase-task-store-core.js";
+import * as TaskFormat from "./ase-task-format.js";
+/*  the maximum number of recent processing log lines kept per agent (by the relay and its
+    subscribers), the maximum number of lines per announcement (as an agent keeps its not yet
+    announced lines while the relay is unreachable), and the duration after which an agent
+    without heartbeat counts as stopped  */
+export const RECENT_MAX = 100;
+export const LINES_MAX = 100;
+export const STALE_MS = 30 * 1000;
+/*  the maximum length of a processing log line message kept by the relay (as
+    the agents themselves already truncate their messages to this length)  */
+export const MSG_MAX = 500;
+/*  the maximum number of projects, of agents per project, and of agents in total
+    held by the relay, and the maximum number of subscribers per project and in total,
+    bounding the memory of the relay against misbehaving or malicious clients  */
+export const PROJECTS_MAX = 128;
+export const AGENTS_MAX = 64;
+export const AGENTS_TOTAL_MAX = 1024;
+export const SUBS_MAX = 64;
+export const SUBS_TOTAL_MAX = 1024;
+/*  append processing log lines to the recent ones, keeping the most recent ones only  */
+export const appendLines = (recent, lines) => lines.length === 0 ? recent : [...recent, ...lines].slice(-RECENT_MAX);
+/*  add two usages, where a field stays null only if it is null in both  */
+export const addUsage = (a, b) => {
+    const add = (x, y) => x === null && y === null ? null : (x ?? 0) + (y ?? 0);
+    return {
+        walltimeSec: a.walltimeSec + b.walltimeSec,
+        costToken: add(a.costToken, b.costToken),
+        costUSD: add(a.costUSD, b.costUSD)
+    };
+};
+/*  the valid agent ids (as derived from host, process id, and agent name)  */
+export const AGENT_ID_RE = /^[A-Za-z0-9][A-Za-z0-9_.-]{0,127}$/;
+/*  the valibot schema entries of a processing log line and of an announcement  */
+const text = (max) => v.pipe(v.string(), v.maxLength(max));
+const lineEntries = {
+    time: v.number(),
+    level: v.picklist(["error", "warning", "info"]),
+    task: text(255),
+    msg: text(2000)
+};
+const status = v.pipe(text(64), v.minLength(1));
+const flowEntries = {
+    input: v.pipe(v.array(status), v.maxLength(32)),
+    activity: v.optional(status),
+    output: v.pipe(v.array(status), v.maxLength(32)),
+    gate: v.optional(status)
+};
+const amount = v.pipe(v.number(), v.minValue(0));
+const usageEntries = {
+    walltimeSec: amount,
+    costToken: v.nullable(amount),
+    costUSD: v.nullable(amount)
+};
+const announceEntries = {
+    kind: v.pipe(text(64), v.minLength(1)),
+    name: v.pipe(text(64), v.minLength(1)),
+    mode: v.optional(text(64), ""),
+    title: v.optional(text(80)),
+    description: v.optional(text(600)),
+    request: v.optional(text(64)),
+    prompt: v.optional(v.picklist(["optional", "ignored"])),
+    host: text(255),
+    pid: v.pipe(v.number(), v.integer(), v.minValue(0)),
+    cwd: v.optional(text(4096)),
+    user: v.optional(text(255)),
+    uid: v.optional(v.pipe(v.number(), v.integer(), v.minValue(-1))),
+    state: v.picklist(["waiting", "busy"]),
+    tasks: v.pipe(v.array(v.pipe(text(255), v.regex(TaskFormat.TASK_ID_RE))), v.maxLength(64))
+};
+/*  the valibot schema of an announcement (strict, as received by the relay)  */
+const announceSchema = v.strictObject({
+    ...announceEntries,
+    states: v.optional(v.strictObject(flowEntries)),
+    started: v.optional(v.number()),
+    usage: v.optional(v.nullable(v.strictObject({
+        total: v.strictObject(usageEntries),
+        last: v.strictObject(usageEntries)
+    })), null),
+    lines: v.pipe(v.array(v.strictObject(lineEntries)), v.maxLength(LINES_MAX))
+});
+/*  the valibot schema of an event frame (lenient on additional fields,
+    as received by the subscribers from a potentially newer relay)  */
+export const frameSchema = v.object({
+    reset: v.optional(v.boolean()),
+    agents: v.optional(v.record(v.pipe(v.string(), v.regex(AGENT_ID_RE)), v.object({
+        ...announceEntries,
+        states: v.optional(v.object(flowEntries)),
+        id: v.pipe(v.string(), v.regex(AGENT_ID_RE)),
+        started: v.number(),
+        usage: v.optional(v.nullable(v.object({
+            total: v.object(usageEntries),
+            last: v.object(usageEntries)
+        })), null),
+        since: v.number(),
+        beat: v.number(),
+        recent: v.pipe(v.array(v.object(lineEntries)), v.maxLength(RECENT_MAX))
+    }))),
+    removed: v.optional(v.array(v.string()))
+});
+/*  the transport-agnostic agent relay: the presence of the agents per project (with
+    a project existing implicitly while it has agents), the removal of the agents
+    without heartbeat, and the emitting of an event frame on every change  */
+export class AgentRelayCore {
+    emit;
+    projects = new Map();
+    timer = null;
+    constructor(emit) {
+        this.emit = emit;
+    }
+    /*  start and stop the periodic removal of the stale agents  */
+    start() {
+        this.timer = setInterval(() => { this.sweep(); }, 5 * 1000);
+    }
+    stop() {
+        if (this.timer !== null)
+            clearInterval(this.timer);
+        this.timer = null;
+        this.projects.clear();
+    }
+    /*  validate a project id and an agent id  */
+    validate(prjId, agentId) {
+        if (!TaskFormat.ID_RE.test(prjId))
+            throw Core.problem(422, `invalid project id "${prjId}" (expected: [A-Za-z0-9_-]+)`);
+        if (agentId !== undefined && !AGENT_ID_RE.test(agentId))
+            throw Core.problem(422, `invalid agent id "${agentId}" (expected: [A-Za-z0-9][A-Za-z0-9_.-]*)`);
+    }
+    /*  the total number of agents of all projects  */
+    agentsTotal() {
+        let total = 0;
+        for (const agents of this.projects.values())
+            total += agents.size;
+        return total;
+    }
+    /*  the projects with agents, each with its number of agents  */
+    projectList() {
+        return [...this.projects.entries()].map(([id, agents]) => ({ id, agents: agents.size }));
+    }
+    /*  the agents of a project  */
+    list(prjId) {
+        this.validate(prjId);
+        return [...(this.projects.get(prjId)?.values() ?? [])];
+    }
+    /*  announce the presence of an agent (also as its heartbeat), keeping the time since
+        which it is in its state while its state is unchanged, appending its added processing
+        log lines to its recent ones, and emitting only its added lines (as a delta), where an
+        agent not announcing its start time (an older one) counts as started at its first announcement  */
+    announce(prjId, agentId, payload) {
+        this.validate(prjId, agentId);
+        const result = v.safeParse(announceSchema, payload);
+        if (!result.success)
+            throw Core.problem(422, `invalid agent announcement: ${result.issues[0].message}` +
+                (result.issues[0].path !== undefined ? ` (at "${v.getDotPath(result.issues[0]) ?? ""}")` : ""));
+        /*  reject a new agent (or a new project) beyond the maximum numbers  */
+        let agents = this.projects.get(prjId);
+        const previous = agents?.get(agentId);
+        if (previous === undefined) {
+            if (agents === undefined && this.projects.size >= PROJECTS_MAX)
+                throw Core.problem(429, `too many projects with agents (maximum: ${PROJECTS_MAX})`);
+            if (agents !== undefined && agents.size >= AGENTS_MAX)
+                throw Core.problem(429, `too many agents of project "${prjId}" (maximum: ${AGENTS_MAX})`);
+            if (this.agentsTotal() >= AGENTS_TOTAL_MAX)
+                throw Core.problem(429, `too many agents in total (maximum: ${AGENTS_TOTAL_MAX})`);
+        }
+        if (agents === undefined) {
+            agents = new Map();
+            this.projects.set(prjId, agents);
+        }
+        /*  update the presence, truncating the messages of the added lines  */
+        const now = Date.now();
+        const { lines: received, ...announced } = result.output;
+        const lines = received.map((line) => line.msg.length <= MSG_MAX ? line :
+            { ...line, msg: `${line.msg.slice(0, MSG_MAX - 1)}…` });
+        const presence = {
+            ...announced, id: agentId,
+            started: announced.started ?? previous?.started ?? now,
+            since: previous !== undefined && previous.state === announced.state ? previous.since : now,
+            beat: now,
+            recent: appendLines(previous?.recent ?? [], lines)
+        };
+        agents.set(agentId, presence);
+        this.emit(prjId, { agents: { [agentId]: { ...presence, recent: lines } } });
+    }
+    /*  remove an agent (on its stopping), where a project without agents ceases to exist  */
+    remove(prjId, agentId) {
+        this.validate(prjId, agentId);
+        const agents = this.projects.get(prjId);
+        if (agents === undefined || !agents.delete(agentId))
+            return;
+        if (agents.size === 0)
+            this.projects.delete(prjId);
+        this.emit(prjId, { removed: [agentId] });
+    }
+    /*  remove all agents without a heartbeat for the stale duration  */
+    sweep() {
+        const limit = Date.now() - STALE_MS;
+        for (const [prjId, agents] of this.projects) {
+            const removed = [...agents.values()].filter((agent) => agent.beat < limit).map((agent) => agent.id);
+            for (const id of removed)
+                agents.delete(id);
+            if (agents.size === 0)
+                this.projects.delete(prjId);
+            if (removed.length > 0)
+                this.emit(prjId, { removed });
+        }
+    }
+}

package/dst/ase-agent-relay-server-bind.js

@@ -0,0 +1,242 @@
+/*
+**  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 Hapi from "@hapi/hapi";
+import { WebSocketServer } from "ws";
+import * as Core from "./ase-task-store-core.js";
+import * as TaskFormat from "./ase-task-format.js";
+import * as Relay from "./ase-agent-relay-core.js";
+import { ServerGuard, urlHost } from "./ase-lib-server-bind.js";
+/*  the route path templates and the JSON payload route options (bounding the
+    request body to the size of an announcement with all its lines at maximum)  */
+const P = "/projects/{prjId}/agents";
+const json = { payload: { parse: true, allow: "application/json", maxBytes: 512 * 1024 } };
+/*  the interval of the keepalive pings of the subscribers, the maximum size of
+    the messages of the subscribers (which send none at all), and the maximum amount
+    of not yet transmitted data of a subscriber (beyond which it cannot keep up)  */
+const PING_MS = 15 * 1000;
+const PAYLOAD_MAX = 4 * 1024;
+const BUFFER_MAX = 1024 * 1024;
+/*  the agent relay endpoints, mountable onto a Hapi server which authenticates all
+    requests and renders the thrown problems (the standalone agent relay server, or the
+    task store server co-hosting the agent relay): the REST endpoints of the agents and
+    the WebSocket event endpoint of the projects, which the hosting server delegates to  */
+export class AgentRelayBinding {
+    log;
+    core;
+    wss = new WebSocketServer({ noServer: true, maxPayload: PAYLOAD_MAX });
+    subs = new Map();
+    unanswered = new WeakSet();
+    timer = null;
+    constructor(log) {
+        this.log = log;
+        this.core = new Relay.AgentRelayCore((prjId, frame) => { this.emit(prjId, frame); });
+    }
+    /*  whether a request path belongs to the agent relay  */
+    static handles(path) {
+        return path === "/agents" || /^\/projects\/[^/]+\/agents(?:\/|$)/.test(path);
+    }
+    /*  start and stop the agent relay and the keepalive pings of the
+        subscribers, closing all subscriptions with close code 1001  */
+    start() {
+        this.core.start();
+        this.timer = setInterval(() => { this.keepalive(); }, PING_MS);
+    }
+    stop() {
+        if (this.timer !== null)
+            clearInterval(this.timer);
+        this.timer = null;
+        for (const subs of this.subs.values())
+            for (const ws of subs)
+                ws.close(1001, "server shutting down");
+        this.subs.clear();
+        this.wss.close();
+        this.core.stop();
+    }
+    /*  ping all subscribers, terminating those which have not answered the previous
+        ping (e.g. on a half-open connection after a network partition or a host crash)  */
+    keepalive() {
+        for (const [prjId, subs] of this.subs)
+            for (const ws of subs) {
+                if (this.unanswered.has(ws)) {
+                    this.log.write("debug", `relay: terminating unresponsive subscriber of project "${prjId}"`);
+                    ws.terminate();
+                    continue;
+                }
+                this.unanswered.add(ws);
+                ws.ping();
+            }
+    }
+    /*  deliver an event frame to the subscribers of a project, terminating those which
+        cannot keep up (as a skipped delta frame would corrupt their view of the agents,
+        and they will receive a fresh snapshot on their reconnection anyway)  */
+    emit(prjId, frame) {
+        const data = JSON.stringify(frame);
+        for (const ws of this.subs.get(prjId) ?? []) {
+            if (ws.readyState !== ws.OPEN)
+                continue;
+            if (ws.bufferedAmount > BUFFER_MAX) {
+                this.log.write("debug", `relay: terminating congested subscriber of project "${prjId}"`);
+                ws.terminate();
+                continue;
+            }
+            ws.send(data);
+        }
+    }
+    /*  handle a (by the hosting server already authenticated) WebSocket handshake on the
+        event endpoint of a project, starting the subscription with the snapshot of its agents  */
+    upgrade(req, socket, head, path, reject) {
+        const m = /^\/projects\/([^/]+)\/agents\/events$/.exec(path);
+        if (m === null) {
+            reject(404, `no WebSocket endpoint "${path}"`);
+            return;
+        }
+        const prjId = m[1];
+        if (!TaskFormat.ID_RE.test(prjId)) {
+            reject(422, `invalid project id "${prjId}" (expected: [A-Za-z0-9_-]+)`);
+            return;
+        }
+        /*  reject a subscriber beyond the maximum numbers  */
+        let total = 0;
+        for (const subs of this.subs.values())
+            total += subs.size;
+        if ((this.subs.get(prjId)?.size ?? 0) >= Relay.SUBS_MAX) {
+            reject(429, `too many subscribers of project "${prjId}" (maximum: ${Relay.SUBS_MAX})`);
+            return;
+        }
+        if (total >= Relay.SUBS_TOTAL_MAX) {
+            reject(429, `too many subscribers in total (maximum: ${Relay.SUBS_TOTAL_MAX})`);
+            return;
+        }
+        this.wss.handleUpgrade(req, socket, head, (ws) => {
+            let subs = this.subs.get(prjId);
+            if (subs === undefined) {
+                subs = new Set();
+                this.subs.set(prjId, subs);
+            }
+            subs.add(ws);
+            this.log.write("debug", `relay: subscribed to agents of project "${prjId}"`);
+            const agents = Object.fromEntries(this.core.list(prjId).map((agent) => [agent.id, agent]));
+            ws.send(JSON.stringify({ reset: true, agents }));
+            ws.on("pong", () => {
+                this.unanswered.delete(ws);
+            });
+            ws.on("close", () => {
+                const subs = this.subs.get(prjId);
+                if (subs !== undefined) {
+                    subs.delete(ws);
+                    if (subs.size === 0)
+                        this.subs.delete(prjId);
+                }
+            });
+            ws.on("error", (err) => {
+                this.log.write("debug", `relay: WebSocket error on agents of project "${prjId}": ${err.message}`);
+            });
+        });
+    }
+    /*  install the REST endpoints (and the plain HTTP fallback of the event endpoint)  */
+    install(server) {
+        const core = this.core;
+        const p = (request) => request.params;
+        server.route({
+            method: "GET",
+            path: "/agents",
+            handler: () => ({ projects: core.projectList() })
+        });
+        server.route({
+            method: "GET",
+            path: P,
+            handler: (request) => ({ agents: core.list(p(request).prjId) })
+        });
+        server.route({
+            method: "PUT",
+            path: `${P}/{agentId}`,
+            options: json,
+            handler: (request, h) => {
+                core.announce(p(request).prjId, p(request).agentId, request.payload);
+                return h.response().code(204);
+            }
+        });
+        server.route({
+            method: "DELETE",
+            path: `${P}/{agentId}`,
+            handler: (request, h) => {
+                core.remove(p(request).prjId, p(request).agentId);
+                return h.response().code(204);
+            }
+        });
+        server.route({
+            method: "GET",
+            path: `${P}/events`,
+            handler: () => {
+                throw Core.problem(426, "the event endpoint requires a WebSocket handshake");
+            }
+        });
+    }
+}
+/*  the standalone agent relay server: bearer token authentication, CORS,
+    problem details rendering, and the agent relay endpoints  */
+export class AgentRelayServer {
+    log;
+    options;
+    server;
+    binding;
+    constructor(log, options) {
+        this.log = log;
+        this.options = options;
+        this.binding = new AgentRelayBinding(log);
+        this.server = Hapi.server({
+            host: options.address,
+            port: options.port,
+            tls: options.tls ?? undefined,
+            routes: {
+                cors: options.cors.length === 0 ? false : {
+                    origin: options.cors,
+                    headers: ["Authorization", "Content-Type"],
+                    maxAge: 86400
+                }
+            }
+        });
+        /*  install the common extensions, logging the requests at debug level
+            only (as the agents announce frequently), and the agent relay endpoints  */
+        const guard = new ServerGuard(log, {
+            label: "relay",
+            token: options.token,
+            failure: "internal agent relay failure (see relay log for details)",
+            level: () => "debug",
+            upgrade: (req, socket, head) => {
+                const url = new URL(req.url ?? "/", "http://localhost");
+                const path = url.pathname;
+                if (!guard.authorized(req.headers.authorization, url.searchParams.get("token") ?? undefined))
+                    guard.rejectUpgrade(socket, 401, "missing or invalid bearer token", path);
+                else
+                    this.binding.upgrade(req, socket, head, path, (status, detail) => {
+                        guard.rejectUpgrade(socket, status, detail, path);
+                    });
+            }
+        });
+        guard.install(this.server);
+        this.binding.install(this.server);
+    }
+    /*  start the server: start the agent relay and bind the listener  */
+    async start() {
+        this.binding.start();
+        try {
+            await this.server.start();
+        }
+        catch (err) {
+            this.binding.stop();
+            throw err;
+        }
+        const scheme = this.options.tls !== null ? "https" : "http";
+        this.log.write("info", `relay: listening on ${scheme}://${urlHost(this.options.address)}:${this.options.port}`);
+    }
+    /*  stop the server: stop the agent relay and unbind the listener  */
+    async stop() {
+        this.binding.stop();
+        await this.server.stop({ timeout: 1000 });
+        this.log.write("info", "relay: terminated");
+    }
+}

package/dst/ase-agent-relay-server-cli.js

@@ -0,0 +1,50 @@
+/*
+**  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 * as v from "valibot";
+import { ServerCommand, configuredTls } from "./ase-lib-server-cli.js";
+import { Config } from "./ase-config-core.js";
+import { configSchema } from "./ase-config-schema.js";
+import * as Server from "./ase-agent-relay-server-bind.js";
+/*  schema for the per-user "relay.yaml"  */
+export const relaySchema = v.nullish(v.strictObject({
+    address: v.optional(v.string()),
+    port: v.optional(v.pipe(v.number(), v.integer(), v.minValue(1), v.maxValue(65535))),
+    token: v.optional(v.string()),
+    pid: v.optional(v.pipe(v.number(), v.integer())),
+    cors: v.optional(v.array(v.string())),
+    tls: v.optional(v.strictObject({
+        cert: v.optional(v.string()),
+        key: v.optional(v.string())
+    }))
+}));
+/*  the configured TLS certificate and key of the agent relay: "project.relay.crt" and
+    "project.relay.key" of the configuration <cfg>, unless "project.relay.url" selects
+    HTTP on this host (as the agents and task boards following it would then fail)  */
+export const relayTls = (cfg) => configuredTls(cfg, "project.relay");
+/*  CLI command group "ase agent relay"  */
+export default class AgentRelayCommand extends ServerCommand {
+    label = "relay";
+    description = "Manage the per-user agent relay server, passing the live presence of the agents to the task boards";
+    name = "relay";
+    schema = relaySchema;
+    prefix = "ASE_AGENT_RELAY";
+    words = "agent relay";
+    probePath = "/agents";
+    /*  the agent relay has no specific configuration  */
+    context(ctx) {
+        return ctx;
+    }
+    /*  the TLS certificate and key configured in the project configuration  */
+    tlsDefaults() {
+        const cfg = new Config("config", configSchema, this.log);
+        cfg.read();
+        return relayTls(cfg);
+    }
+    /*  create the standalone agent relay server  */
+    async create(_ctx, config) {
+        return { server: new Server.AgentRelayServer(this.log, config), facts: {} };
+    }
+}