@datalayer/agent-runtimes 1.5.44 → 1.5.46

package/lib/portable/hosts/observability.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Credentials by their shape, for every host at once (redacting another
+ * host's shape too is never wrong): Slack's bot, user and app tokens,
+ * Discord's bot tokens (`<base64 id>.<6>.<27+>`), Datalayer's host keys,
+ * link and handoff codes, JWTs (which a Discord interaction token is not, so
+ * it is named by its field), and bearer credentials.
+ */
+export declare const TOKEN_PATTERNS: readonly RegExp[];
+export declare const REDACTED = "[redacted]";
+/** A copy of a value with every secret field and credential-like string redacted. */
+export declare function redact(value: unknown, depth?: number): unknown;
+/**
+ * A copy with credentials redacted but words kept: what an audited,
+ * privileged payload read shows (S-405).
+ */
+export declare function redactCredentials(value: unknown, depth?: number): unknown;
+/**
+ * A stable pseudonym of an id: the same id and salt, the same 16 hex
+ * characters; never reversible. Each host salts with its own name.
+ */
+export declare function pseudonym(value: string, salt: string): string;
+export type LogSink = (line: string) => void;
+/** A JSON logger whose every field is redacted. */
+export declare class Logger {
+    #private;
+    readonly sink: LogSink;
+    readonly clock: () => Date;
+    /** What the audit's pseudonyms are salted with: the host's own. */
+    readonly salt: string;
+    constructor(sink?: LogSink, clock?: () => Date, 
+    /** What the audit's pseudonyms are salted with: the host's own. */
+    salt?: string);
+    info(event: string, fields?: Record<string, unknown>): void;
+    warn(event: string, fields?: Record<string, unknown>): void;
+    error(event: string, fields?: Record<string, unknown>): void;
+    /**
+     * An identity audit event (SLACK S-103): who (pseudonymous), which installation
+     * (its hash), what happened, why. Never a code, a token or a principal's
+     * name.
+     */
+    audit(event: 'identity.linked' | 'identity.unlinked' | 'identity.refused' | 'admin.changed' | 'payload.read', fields: {
+        installation: string;
+        /** The host user it is about. */
+        user?: string;
+        reason?: string;
+        by?: string;
+        [name: string]: unknown;
+    }): void;
+}
+/** Tracing: one span per job, named by what it is, its ids pseudonymous. */
+export interface Tracer {
+    span<T>(name: string, attributes: Record<string, string | number | boolean>, work: () => Promise<T>): Promise<T>;
+}
+/** No tracing: what tests and development use. */
+export declare const noTracer: Tracer;
+/**
+ * Spans as log lines with their duration and outcome, until the service runs
+ * beside the plane's OTEL collector (`OTEL_EXPORTER_OTLP_TRACES_ENDPOINT`,
+ * the Datalayer convention); each host names its attributes
+ * (`datalayer.slack.*`, `datalayer.discord.*`), pseudonymous by construction.
+ */
+export declare class LogTracer implements Tracer {
+    readonly logger: Logger;
+    readonly now: () => number;
+    constructor(logger: Logger, now?: () => number);
+    span<T>(name: string, attributes: Record<string, string | number | boolean>, work: () => Promise<T>): Promise<T>;
+}

package/lib/portable/hosts/observability.js

@@ -0,0 +1,171 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+import { createHash } from 'node:crypto';
+/**
+ * Logs, audit events and traces without secrets or words (SLACK §9, §12.2;
+ * DISCORD §9, §12.2): every routine line is JSON whose fields pass `redact`;
+ * host and Datalayer ids are pseudonymous (`pseudonym`), so a trace can be
+ * followed `host event → job → installation hash → session → host message`
+ * without naming an installation, a person or what they wrote. Moved from
+ * the Slack service (plans/DISCORD.md DC-004).
+ *
+ * @module portable/hosts/observability
+ */
+/** Field names whose values are never logged: credentials, codes and words. */
+const SECRET_NAME = /(token|secret|password|authorization|cookie|signature|^code$|_code$|host_?key|api_?key|private|^text$|^body$|prompt|message|markdown|arguments|payload|value)/i;
+/**
+ * Credentials by their shape, for every host at once (redacting another
+ * host's shape too is never wrong): Slack's bot, user and app tokens,
+ * Discord's bot tokens (`<base64 id>.<6>.<27+>`), Datalayer's host keys,
+ * link and handoff codes, JWTs (which a Discord interaction token is not, so
+ * it is named by its field), and bearer credentials.
+ */
+export const TOKEN_PATTERNS = [
+    /xox[abprse]-[A-Za-z0-9-]{8,}/,
+    /xapp-[A-Za-z0-9-]{8,}/,
+    /[A-Za-z0-9_-]{23,28}\.[A-Za-z0-9_-]{6}\.[A-Za-z0-9_-]{27,40}/,
+    /dlh[kco]_[A-Za-z0-9_-]{8,}/,
+    /eyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{5,}/,
+    /Bearer\s+[A-Za-z0-9._~+/=-]{8,}/,
+];
+/** Values that look like credentials wherever they appear. */
+const SECRET_VALUE = new RegExp(`\\b(${TOKEN_PATTERNS.map(pattern => pattern.source).join('|')})`, 'g');
+export const REDACTED = '[redacted]';
+/** A copy of a value with every secret field and credential-like string redacted. */
+export function redact(value, depth = 0) {
+    if (depth > 6)
+        return REDACTED;
+    if (typeof value === 'string')
+        return value.replace(SECRET_VALUE, REDACTED);
+    if (Array.isArray(value))
+        return value.map(one => redact(one, depth + 1));
+    if (value instanceof Error)
+        return { name: value.name, message: redact(value.message, depth + 1) };
+    if (value && typeof value === 'object') {
+        const out = {};
+        for (const [name, one] of Object.entries(value))
+            out[name] = SECRET_NAME.test(name) ? REDACTED : redact(one, depth + 1);
+        return out;
+    }
+    return value;
+}
+/** Field names of credentials only: what even a privileged reader never sees. */
+const CREDENTIAL_NAME = /(token|secret|password|authorization|cookie|signature|host_?key|api_?key|private_?key)/i;
+/**
+ * A copy with credentials redacted but words kept: what an audited,
+ * privileged payload read shows (S-405).
+ */
+export function redactCredentials(value, depth = 0) {
+    if (depth > 8)
+        return REDACTED;
+    if (typeof value === 'string')
+        return value.replace(SECRET_VALUE, REDACTED);
+    if (Array.isArray(value))
+        return value.map(one => redactCredentials(one, depth + 1));
+    if (value && typeof value === 'object') {
+        const out = {};
+        for (const [name, one] of Object.entries(value))
+            out[name] = CREDENTIAL_NAME.test(name)
+                ? REDACTED
+                : redactCredentials(one, depth + 1);
+        return out;
+    }
+    return value;
+}
+/**
+ * A stable pseudonym of an id: the same id and salt, the same 16 hex
+ * characters; never reversible. Each host salts with its own name.
+ */
+export function pseudonym(value, salt) {
+    return createHash('sha256')
+        .update(`${salt}:${value}`)
+        .digest('hex')
+        .slice(0, 16);
+}
+/** A JSON logger whose every field is redacted. */
+export class Logger {
+    sink;
+    clock;
+    salt;
+    constructor(sink = line => process.stdout.write(`${line}\n`), clock = () => new Date(), 
+    /** What the audit's pseudonyms are salted with: the host's own. */
+    salt = 'datalayer-host') {
+        this.sink = sink;
+        this.clock = clock;
+        this.salt = salt;
+    }
+    #write(level, event, fields) {
+        this.sink(JSON.stringify({
+            at: this.clock().toISOString(),
+            level,
+            event,
+            ...redact(fields),
+        }));
+    }
+    info(event, fields = {}) {
+        this.#write('info', event, fields);
+    }
+    warn(event, fields = {}) {
+        this.#write('warn', event, fields);
+    }
+    error(event, fields = {}) {
+        this.#write('error', event, fields);
+    }
+    /**
+     * An identity audit event (SLACK S-103): who (pseudonymous), which installation
+     * (its hash), what happened, why. Never a code, a token or a principal's
+     * name.
+     */
+    audit(event, fields) {
+        const { installation, user, by, ...rest } = fields;
+        this.#write('audit', event, {
+            ...rest,
+            installation: pseudonym(installation, this.salt),
+            ...(user ? { user: pseudonym(user, this.salt) } : {}),
+            ...(by ? { by: pseudonym(by, this.salt) } : {}),
+        });
+    }
+}
+/** No tracing: what tests and development use. */
+export const noTracer = {
+    span: async (_name, _attributes, work) => work(),
+};
+/**
+ * Spans as log lines with their duration and outcome, until the service runs
+ * beside the plane's OTEL collector (`OTEL_EXPORTER_OTLP_TRACES_ENDPOINT`,
+ * the Datalayer convention); each host names its attributes
+ * (`datalayer.slack.*`, `datalayer.discord.*`), pseudonymous by construction.
+ */
+export class LogTracer {
+    logger;
+    now;
+    constructor(logger, now = () => performance.now()) {
+        this.logger = logger;
+        this.now = now;
+    }
+    async span(name, attributes, work) {
+        const started = this.now();
+        try {
+            const result = await work();
+            this.logger.info('span', {
+                name,
+                ...attributes,
+                duration_ms: Math.round(this.now() - started),
+                outcome: 'ok',
+            });
+            return result;
+        }
+        catch (error) {
+            this.logger.info('span', {
+                name,
+                ...attributes,
+                duration_ms: Math.round(this.now() - started),
+                outcome: 'error',
+                error_name: error instanceof Error ? error.name : 'unknown',
+            });
+            throw error;
+        }
+    }
+}

package/lib/portable/hosts/postgresQueue.d.ts

@@ -0,0 +1,55 @@
+/**
+ * The durable work queue on Postgres: jobs claimed with `FOR UPDATE SKIP
+ * LOCKED`, leased and renewed while worked, retried with backoff, dead after
+ * five attempts, an ingress claim and its job kept in one transaction. Its
+ * tables are `<prefix>_jobs`, `<prefix>_event_claims` and
+ * `<prefix>_job_replays` (`hostSchemaSql`). Moved from the Slack service
+ * (plans/DISCORD.md DC-004).
+ *
+ * @module portable/hosts/postgresQueue
+ */
+import { type ConnectionPool, type WorkQueue } from './queue';
+export declare class PostgresWorkQueue<T> implements WorkQueue<T> {
+    #private;
+    readonly database: ConnectionPool;
+    /** The host's table prefix: `slack`, `discord`. */
+    readonly tablePrefix: string;
+    readonly pollIntervalMs: number;
+    /**
+     * How often a job being worked renews its lease (S-207): well within the
+     * five minutes after which `reclaimAbandonedJobs` takes a job back, so
+     * only a worker that died loses its job, not one answering a long turn.
+     */
+    readonly leaseRenewMs: number;
+    constructor(database: ConnectionPool, 
+    /** The host's table prefix: `slack`, `discord`. */
+    tablePrefix: string, pollIntervalMs?: number, 
+    /**
+     * How often a job being worked renews its lease (S-207): well within the
+     * five minutes after which `reclaimAbandonedJobs` takes a job back, so
+     * only a worker that died loses its job, not one answering a long turn.
+     */
+    leaseRenewMs?: number);
+    enqueue(item: T, idempotencyKey?: string): Promise<boolean>;
+    ready(): Promise<boolean>;
+    /** Jobs that failed five times, with their metadata only: what the dead-letter tool lists. */
+    dead(limit?: number): Promise<Array<{
+        id: string;
+        attempts: number;
+        lastError: string | null;
+        createdAt: string;
+        kind: string;
+    }>>;
+    /**
+     * Put a dead job back to work: once, by id, the replay kept with who asked
+     * in the same transaction (`<prefix>_job_replays`, SLACK S-405), refused or not.
+     */
+    replay(id: string, operator: string): Promise<boolean>;
+    /**
+     * A dead job's payload, and only a dead one's (S-405): a live job, or an id
+     * that is no job, has none to read here.
+     */
+    payloadOf(id: string): Promise<unknown>;
+    start(handler: (item: T) => Promise<void>): void;
+    stop(): Promise<void>;
+}

package/lib/portable/hosts/postgresQueue.js

@@ -0,0 +1,217 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * The durable work queue on Postgres: jobs claimed with `FOR UPDATE SKIP
+ * LOCKED`, leased and renewed while worked, retried with backoff, dead after
+ * five attempts, an ingress claim and its job kept in one transaction. Its
+ * tables are `<prefix>_jobs`, `<prefix>_event_claims` and
+ * `<prefix>_job_replays` (`hostSchemaSql`). Moved from the Slack service
+ * (plans/DISCORD.md DC-004).
+ *
+ * @module portable/hosts/postgresQueue
+ */
+import { tablePrefixOf, } from './queue';
+export class PostgresWorkQueue {
+    database;
+    tablePrefix;
+    pollIntervalMs;
+    leaseRenewMs;
+    #handler;
+    #loop;
+    #stopping = false;
+    #jobs;
+    #claims;
+    #replays;
+    constructor(database, 
+    /** The host's table prefix: `slack`, `discord`. */
+    tablePrefix, pollIntervalMs = 250, 
+    /**
+     * How often a job being worked renews its lease (S-207): well within the
+     * five minutes after which `reclaimAbandonedJobs` takes a job back, so
+     * only a worker that died loses its job, not one answering a long turn.
+     */
+    leaseRenewMs = 60_000) {
+        this.database = database;
+        this.tablePrefix = tablePrefix;
+        this.pollIntervalMs = pollIntervalMs;
+        this.leaseRenewMs = leaseRenewMs;
+        const prefix = tablePrefixOf(tablePrefix);
+        this.#jobs = `${prefix}_jobs`;
+        this.#claims = `${prefix}_event_claims`;
+        this.#replays = `${prefix}_job_replays`;
+    }
+    async enqueue(item, idempotencyKey) {
+        if (!idempotencyKey) {
+            await this.database.query(`INSERT INTO ${this.#jobs} (payload) VALUES ($1)`, [item]);
+            return true;
+        }
+        // The idempotency key and its job in one transaction (§7.1, 4).
+        const client = await this.database.connect();
+        try {
+            await client.query('BEGIN');
+            const claimed = await client.query(`INSERT INTO ${this.#claims} (event_id) VALUES ($1) ON CONFLICT DO NOTHING RETURNING event_id`, [`ingress:${idempotencyKey}`]);
+            if (claimed.rowCount === 1)
+                await client.query(`INSERT INTO ${this.#jobs} (payload) VALUES ($1)`, [
+                    item,
+                ]);
+            await client.query('COMMIT');
+            return claimed.rowCount === 1;
+        }
+        catch (error) {
+            await client.query('ROLLBACK');
+            throw error;
+        }
+        finally {
+            client.release();
+        }
+    }
+    async ready() {
+        try {
+            await this.database.query(`SELECT 1 FROM ${this.#jobs} LIMIT 1`);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    /** Jobs that failed five times, with their metadata only: what the dead-letter tool lists. */
+    async dead(limit = 50) {
+        const result = await this.database.query(`SELECT id::text, attempts, last_error, created_at,
+              CASE WHEN payload ? 'delivery' THEN 'delivery'
+                   WHEN payload ? 'prompt' THEN 'prompt'
+                   ELSE 'other' END AS kind
+       FROM ${this.#jobs} WHERE state = 'dead' ORDER BY id LIMIT $1`, [limit]);
+        return result.rows.map(row => ({
+            attempts: row.attempts,
+            createdAt: new Date(row.created_at).toISOString(),
+            id: row.id,
+            kind: row.kind ?? 'other',
+            lastError: row.last_error,
+        }));
+    }
+    /**
+     * Put a dead job back to work: once, by id, the replay kept with who asked
+     * in the same transaction (`<prefix>_job_replays`, SLACK S-405), refused or not.
+     */
+    async replay(id, operator) {
+        if (!/^\d+$/.test(id))
+            return false;
+        const client = await this.database.connect();
+        try {
+            await client.query('BEGIN');
+            const result = await client.query(`UPDATE ${this.#jobs} SET state = 'ready', attempts = 0, available_at = now(), last_error = NULL WHERE id = $1 AND state = 'dead'`, [id]);
+            const replayed = result.rowCount === 1;
+            await client.query(`INSERT INTO ${this.#replays} (job_id, operator, replayed) VALUES ($1, $2, $3)`, [id, operator, replayed]);
+            await client.query('COMMIT');
+            return replayed;
+        }
+        catch (error) {
+            await client.query('ROLLBACK');
+            throw error;
+        }
+        finally {
+            client.release();
+        }
+    }
+    /**
+     * A dead job's payload, and only a dead one's (S-405): a live job, or an id
+     * that is no job, has none to read here.
+     */
+    async payloadOf(id) {
+        if (!/^\d+$/.test(id))
+            return undefined;
+        const result = await this.database.query(`SELECT payload FROM ${this.#jobs} WHERE id = $1 AND state = 'dead'`, [id]);
+        return result.rows[0]?.payload;
+    }
+    start(handler) {
+        if (this.#loop)
+            throw new Error('The PostgreSQL work queue has already started.');
+        this.#handler = handler;
+        this.#stopping = false;
+        this.#loop = this.#run();
+    }
+    async stop() {
+        this.#stopping = true;
+        await this.#loop;
+        this.#loop = undefined;
+        this.#handler = undefined;
+    }
+    async #run() {
+        while (!this.#stopping) {
+            const job = await this.#claim();
+            if (!job) {
+                await delay(this.pollIntervalMs);
+                continue;
+            }
+            const lease = setInterval(() => {
+                void this.database
+                    .query(`UPDATE ${this.#jobs} SET locked_at = now() WHERE id = $1 AND state = 'processing'`, [job.id])
+                    .catch(() => undefined); // the next renewal, or the reclaim, decides
+            }, this.leaseRenewMs);
+            lease.unref?.();
+            try {
+                await this.#handler?.(job.payload);
+                await this.database.query(`DELETE FROM ${this.#jobs} WHERE id = $1`, [
+                    job.id,
+                ]);
+            }
+            catch (error) {
+                await this.#fail(job, error);
+            }
+            finally {
+                clearInterval(lease);
+            }
+        }
+    }
+    async #claim() {
+        const client = await this.database.connect();
+        try {
+            await client.query('BEGIN');
+            await reclaimAbandonedJobs(client, this.#jobs);
+            const selected = await client.query(`SELECT id::text, payload, attempts
+         FROM ${this.#jobs}
+         WHERE state = 'ready' AND available_at <= now()
+         ORDER BY id
+         FOR UPDATE SKIP LOCKED
+         LIMIT 1`);
+            const job = selected.rows[0];
+            if (!job) {
+                await client.query('COMMIT');
+                return undefined;
+            }
+            await client.query(`UPDATE ${this.#jobs}
+         SET state = 'processing', attempts = attempts + 1, locked_at = now()
+         WHERE id = $1`, [job.id]);
+            await client.query('COMMIT');
+            return { ...job, attempts: job.attempts + 1 };
+        }
+        catch (error) {
+            await client.query('ROLLBACK');
+            throw error;
+        }
+        finally {
+            client.release();
+        }
+    }
+    async #fail(job, error) {
+        const message = error instanceof Error ? error.message : 'Unknown worker failure';
+        if (job.attempts >= 5) {
+            await this.database.query(`UPDATE ${this.#jobs} SET state = 'dead', last_error = $2, locked_at = NULL WHERE id = $1`, [job.id, message.slice(0, 2_000)]);
+            return;
+        }
+        const delaySeconds = Math.min(300, 2 ** job.attempts);
+        await this.database.query(`UPDATE ${this.#jobs}
+       SET state = 'ready', available_at = now() + ($2 * interval '1 second'),
+           last_error = $3, locked_at = NULL
+       WHERE id = $1`, [job.id, delaySeconds, message.slice(0, 2_000)]);
+    }
+}
+async function reclaimAbandonedJobs(client, jobs) {
+    await client.query(`UPDATE ${jobs}
+     SET state = 'ready', available_at = now(), locked_at = NULL,
+         last_error = 'Worker lease expired'
+     WHERE state = 'processing' AND locked_at < now() - interval '5 minutes'`);
+}
+const delay = async (milliseconds) => new Promise(resolve => setTimeout(resolve, milliseconds));

package/lib/portable/hosts/queue.d.ts

@@ -0,0 +1,47 @@
+/**
+ * A host's durable work queue, its in-memory development stand-in, and the
+ * structural Postgres connection every Postgres implementation here takes
+ * (`pg.Pool` and `pg.PoolClient` satisfy it: no `pg` import). Moved from the
+ * Slack service (plans/DISCORD.md DC-004).
+ *
+ * @module portable/hosts/queue
+ */
+/** What a query answers: its rows, and how many it changed. */
+export type QueryAnswer<R> = {
+    rows: R[];
+    rowCount: number | null;
+};
+/** A Postgres connection as the hosts code uses it: `pg.Pool` or `pg.PoolClient`. */
+export interface Queryable {
+    query<R extends {
+        [column: string]: any;
+    } = any>(text: string, values?: any[]): Promise<QueryAnswer<R>>;
+}
+/** A pool of connections, one taken for a transaction: `pg.Pool`. */
+export interface ConnectionPool extends Queryable {
+    connect(): Promise<Queryable & {
+        release(): void;
+    }>;
+}
+/** A table prefix a host's tables carry (`slack`, `discord`): lowercase letters and digits. */
+export declare function tablePrefixOf(prefix: string): string;
+export interface WorkQueue<T> {
+    /**
+     * Persist one job. With an idempotency key (a host event or action id),
+     * the key and the job are kept in one transaction and a second job under
+     * the same key is not enqueued: `false`.
+     */
+    enqueue(item: T, idempotencyKey?: string): Promise<boolean>;
+    /** Whether the queue can take durable work now: what readiness reports. */
+    ready(): Promise<boolean>;
+    start(handler: (item: T) => Promise<void>): void;
+    stop(): Promise<void>;
+}
+/** In-process development queue. A durable adapter is required in production. */
+export declare class MemoryWorkQueue<T> implements WorkQueue<T> {
+    #private;
+    enqueue(item: T, idempotencyKey?: string): Promise<boolean>;
+    ready(): Promise<boolean>;
+    start(handler: (item: T) => Promise<void>): void;
+    stop(): Promise<void>;
+}

package/lib/portable/hosts/queue.js

@@ -0,0 +1,63 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/** A table prefix a host's tables carry (`slack`, `discord`): lowercase letters and digits. */
+export function tablePrefixOf(prefix) {
+    if (!/^[a-z][a-z0-9]{1,31}$/.test(prefix)) {
+        throw new Error(`A table prefix is lowercase letters and digits, a letter first: ${prefix}.`);
+    }
+    return prefix;
+}
+/** In-process development queue. A durable adapter is required in production. */
+export class MemoryWorkQueue {
+    #items = [];
+    #keys = new Set();
+    #handler;
+    #running = false;
+    async enqueue(item, idempotencyKey) {
+        if (idempotencyKey) {
+            if (this.#keys.has(idempotencyKey)) {
+                return false;
+            }
+            this.#keys.add(idempotencyKey);
+        }
+        this.#items.push(item);
+        queueMicrotask(() => void this.#drain());
+        return true;
+    }
+    async ready() {
+        return true;
+    }
+    start(handler) {
+        this.#handler = handler;
+        void this.#drain();
+    }
+    async stop() {
+        this.#handler = undefined;
+        while (this.#running) {
+            await new Promise(resolve => setTimeout(resolve, 5));
+        }
+    }
+    async #drain() {
+        if (this.#running || !this.#handler) {
+            return;
+        }
+        this.#running = true;
+        try {
+            while (this.#items.length > 0) {
+                const handler = this.#handler;
+                if (!handler) {
+                    break;
+                }
+                const item = this.#items.shift();
+                if (item !== undefined) {
+                    await handler(item);
+                }
+            }
+        }
+        finally {
+            this.#running = false;
+        }
+    }
+}