@datalayer/agent-runtimes 1.5.45 → 1.5.46

package/lib/portable/hosts/health.js

@@ -0,0 +1,92 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * Liveness and readiness (SLACK §10, S-101; DISCORD §10): `/healthz` says the
+ * process answers; `/readyz` says it can take durable work now — its store
+ * and its queue answer — and never asks the host or Datalayer, so a
+ * transient outage of either does not take the pods out of service: accepted
+ * work waits in the queue instead. And the window a signed host request's
+ * timestamp must fall in. Moved from the Slack service (plans/DISCORD.md
+ * DC-004).
+ *
+ * @module portable/hosts/health
+ */
+import { createServer, } from 'node:http';
+/** Each check, at most `timeoutMs`: a check that throws or is late is not ready. */
+export async function readiness(checks, timeoutMs = 2_000) {
+    const results = {};
+    await Promise.all(Object.entries(checks).map(async ([name, check]) => {
+        let timer;
+        try {
+            results[name] = await Promise.race([
+                check(),
+                new Promise(resolve => {
+                    timer = setTimeout(() => resolve(false), timeoutMs);
+                }),
+            ]);
+        }
+        catch {
+            results[name] = false;
+        }
+        finally {
+            if (timer) {
+                clearTimeout(timer);
+            }
+        }
+    }));
+    return {
+        checks: results,
+        ready: Object.values(results).every(Boolean),
+    };
+}
+function json(response, status, body) {
+    response.writeHead(status, {
+        'cache-control': 'no-store',
+        'content-type': 'application/json',
+    });
+    response.end(JSON.stringify(body));
+}
+/** The health paths, and what each answers. */
+export const HEALTH_PATHS = ['/healthz', '/readyz'];
+/**
+ * Answer `GET /healthz` or `GET /readyz`; `false` for any other request,
+ * which the caller answers.
+ */
+export function answerHealth(checks, request, response) {
+    const path = (request.url ?? '').split('?')[0];
+    if (request.method !== 'GET') {
+        return false;
+    }
+    if (path === '/healthz') {
+        json(response, 200, { status: 'ok' });
+        return true;
+    }
+    if (path === '/readyz') {
+        void readiness(checks).then(answer => json(response, answer.ready ? 200 : 503, answer));
+        return true;
+    }
+    return false;
+}
+/** A worker's own server: its health and readiness only (no host route). */
+export function healthServer(checks) {
+    return createServer((request, response) => {
+        if (!answerHealth(checks, request, response)) {
+            response.writeHead(404);
+            response.end();
+        }
+    });
+}
+/** How far a signed host request's timestamp may be from now, either way (SLACK §7.1, 1; DISCORD §7.1, 1). */
+export const REQUEST_WINDOW_SECONDS = 5 * 60;
+/**
+ * Whether a request's timestamp header (Slack's `X-Slack-Request-Timestamp`,
+ * Discord's `X-Signature-Timestamp`) is within five minutes of now, in the
+ * past or the future: a replay with a skewed clock is refused too.
+ */
+export function timestampWithinWindow(header, nowSeconds = Math.floor(Date.now() / 1000)) {
+    const value = Number(Array.isArray(header) ? header[0] : header);
+    return (Number.isInteger(value) &&
+        Math.abs(nowSeconds - value) <= REQUEST_WINDOW_SECONDS);
+}

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

@@ -0,0 +1,40 @@
+/**
+ * What a chat host service (Slack, Discord) shares, on Node: the ai-agents
+ * host contracts and client, the agent client over the session API, the
+ * semantic events a turn is reduced to, approval renderers, deliveries, the
+ * turn's state, application resolution, the durable queue, quotas, secrets
+ * at rest, observability, dead letters, health, the shared schema and the
+ * forbidden-graph gate (plans/DISCORD.md §4.2, DC-004, DC-005).
+ *
+ * Imported as `@datalayer/agent-runtimes/lib/portable/hosts`, and only by a
+ * Node service, which bundles it with esbuild. It reaches `src/portable/` and
+ * this folder only, and the packages `zod`, `node:crypto` and `node:http`;
+ * never React, DOM, Jupyter, Lumino, Primer, Reactor, `pg` or another folder
+ * of Agent Runtimes (`src/__tests__/portable.unit.test.ts` holds it to that).
+ * It imports its siblings by name, never `'../index'`, whose types reach
+ * Reactor; so a service never imports `@datalayer/agent-runtimes/lib/portable`
+ * itself: what it needs of it is re-exported here.
+ *
+ * @module portable/hosts
+ */
+export { AgUiFrames, readRunStream, type AgUiEvent } from '../agui';
+export * from '../semantic';
+export { askQuestionOf, semanticOf, turnOf, type TurnInfo, } from '../semanticOfAgUi';
+export * from './contracts';
+export { DatalayerHostClient, HostRefusedError, type BoundHost, type HostSelf, } from './client';
+export { agUiEventsOf, assertTrustedStreamUrl, DevelopmentCredentials, HostKeyCredentials, hostSessionOf, HostStarters, HttpAgentClient, InstallationCredentials, lastAnswer, type AgentClient, type HostCredentials, type HostKeyLookup, type HostSession, type HostShape, type HostTurnRequest, type Place, type Starter, type StarterSource, type TurnStream, } from './agentClient';
+export { hostSessionUid } from './sessionUid';
+export { DATALAYER_ONLY, RENDERERS, renderApproval, type RenderedAction, type RenderedField, } from './approvalRenderers';
+export { DELIVERY_PATH, DELIVERY_ROUTE, DeliveryPoller, deliveryRoute, receiveDelivery, type BoundHostKey, type DeliveryClaimStore, type DeliveryJob, type DeliverySink, } from './deliveries';
+export { TurnState, type TurnEnding, type TurnFile, type TurnTool, } from './turnState';
+export { resolveApplication, usableAllowances, type AllowanceView, type ApplicationRefusal, type ApplicationResolution, type ChannelRule, } from './resolution';
+export { MemoryWorkQueue, tablePrefixOf, type ConnectionPool, type Queryable, type QueryAnswer, type WorkQueue, } from './queue';
+export { PostgresWorkQueue } from './postgresQueue';
+export { DEFAULT_QUOTAS, MemoryQuotaStore, PostgresQuotaStore, quotaEntries, quotaWords, resetOf, userQuotaKey, windowOf, type QuotaEntry, type QuotaLimits, type QuotaScope, type QuotaStore, type QuotaTake, type QuotaTaken, } from './quotas';
+export { SecretCipher, type EncryptedSecret } from './secretCipher';
+export { Logger, LogTracer, noTracer, pseudonym, redact, redactCredentials, REDACTED, TOKEN_PATTERNS, type LogSink, type Tracer, } from './observability';
+export { DEAD_LETTERS_USAGE, DeadLetters, deadLetters, payloadHash, runDeadLettersCli, type CliOutput, type DeadLetter, } from './deadLetters';
+export { answerHealth, HEALTH_PATHS, healthServer, readiness, REQUEST_WINDOW_SECONDS, timestampWithinWindow, type ReadinessChecks, } from './health';
+export { systemClock, type Clock } from './rateLimit';
+export { applyHostSchema, hostSchemaSql, hostTables } from './schema';
+export { FORBIDDEN, forbiddenInBundle, forbiddenInGraph, forbiddenInInstalled, importsOf, installedGraph, isForbidden, packageOf, productionGraph, type BundleMetafile, type InstalledTree, type Lockfile, type Reached, } from './forbiddenGraph';

package/lib/portable/hosts/index.js

@@ -0,0 +1,45 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * What a chat host service (Slack, Discord) shares, on Node: the ai-agents
+ * host contracts and client, the agent client over the session API, the
+ * semantic events a turn is reduced to, approval renderers, deliveries, the
+ * turn's state, application resolution, the durable queue, quotas, secrets
+ * at rest, observability, dead letters, health, the shared schema and the
+ * forbidden-graph gate (plans/DISCORD.md §4.2, DC-004, DC-005).
+ *
+ * Imported as `@datalayer/agent-runtimes/lib/portable/hosts`, and only by a
+ * Node service, which bundles it with esbuild. It reaches `src/portable/` and
+ * this folder only, and the packages `zod`, `node:crypto` and `node:http`;
+ * never React, DOM, Jupyter, Lumino, Primer, Reactor, `pg` or another folder
+ * of Agent Runtimes (`src/__tests__/portable.unit.test.ts` holds it to that).
+ * It imports its siblings by name, never `'../index'`, whose types reach
+ * Reactor; so a service never imports `@datalayer/agent-runtimes/lib/portable`
+ * itself: what it needs of it is re-exported here.
+ *
+ * @module portable/hosts
+ */
+// The run stream and its reduction, from the portable entry's own modules.
+export { AgUiFrames, readRunStream } from '../agui';
+export * from '../semantic';
+export { askQuestionOf, semanticOf, turnOf, } from '../semanticOfAgUi';
+export * from './contracts';
+export { DatalayerHostClient, HostRefusedError, } from './client';
+export { agUiEventsOf, assertTrustedStreamUrl, DevelopmentCredentials, HostKeyCredentials, hostSessionOf, HostStarters, HttpAgentClient, InstallationCredentials, lastAnswer, } from './agentClient';
+export { hostSessionUid } from './sessionUid';
+export { DATALAYER_ONLY, RENDERERS, renderApproval, } from './approvalRenderers';
+export { DELIVERY_PATH, DELIVERY_ROUTE, DeliveryPoller, deliveryRoute, receiveDelivery, } from './deliveries';
+export { TurnState, } from './turnState';
+export { resolveApplication, usableAllowances, } from './resolution';
+export { MemoryWorkQueue, tablePrefixOf, } from './queue';
+export { PostgresWorkQueue } from './postgresQueue';
+export { DEFAULT_QUOTAS, MemoryQuotaStore, PostgresQuotaStore, quotaEntries, quotaWords, resetOf, userQuotaKey, windowOf, } from './quotas';
+export { SecretCipher } from './secretCipher';
+export { Logger, LogTracer, noTracer, pseudonym, redact, redactCredentials, REDACTED, TOKEN_PATTERNS, } from './observability';
+export { DEAD_LETTERS_USAGE, DeadLetters, deadLetters, payloadHash, runDeadLettersCli, } from './deadLetters';
+export { answerHealth, HEALTH_PATHS, healthServer, readiness, REQUEST_WINDOW_SECONDS, timestampWithinWindow, } from './health';
+export { systemClock } from './rateLimit';
+export { applyHostSchema, hostSchemaSql, hostTables } from './schema';
+export { FORBIDDEN, forbiddenInBundle, forbiddenInGraph, forbiddenInInstalled, importsOf, installedGraph, isForbidden, packageOf, productionGraph, } from './forbiddenGraph';

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>;
+}