@datalayer/agent-runtimes 1.5.45 → 1.5.47

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

@@ -0,0 +1,19 @@
+/**
+ * The tables every host service keeps the same way, under its own prefix:
+ * ingress claims and the work queue (`<prefix>_event_claims`,
+ * `<prefix>_jobs`), quota counts (`<prefix>_usage`), privileged payload reads
+ * (`<prefix>_payload_access`) and dead-job replays (`<prefix>_job_replays`).
+ * Their final shapes, as idempotent statements: a service applies them
+ * before its own migrations, every time. TypeScript strings, since the npm
+ * tarball ships no `.sql`. Moved from the Slack service's migrations 001,
+ * 004 and 007 (plans/DISCORD.md DC-004).
+ *
+ * @module portable/hosts/schema
+ */
+import { type Queryable } from './queue';
+/** The shared tables of one host, as one idempotent script. */
+export declare function hostSchemaSql(tablePrefix: string): string;
+/** The tables `hostSchemaSql` makes, by name: what a test and an operator check. */
+export declare function hostTables(tablePrefix: string): string[];
+/** Apply the shared tables of one host: idempotent, before the service's own migrations. */
+export declare function applyHostSchema(database: Queryable, tablePrefix: string): Promise<void>;

package/lib/portable/hosts/schema.js

@@ -0,0 +1,81 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * The tables every host service keeps the same way, under its own prefix:
+ * ingress claims and the work queue (`<prefix>_event_claims`,
+ * `<prefix>_jobs`), quota counts (`<prefix>_usage`), privileged payload reads
+ * (`<prefix>_payload_access`) and dead-job replays (`<prefix>_job_replays`).
+ * Their final shapes, as idempotent statements: a service applies them
+ * before its own migrations, every time. TypeScript strings, since the npm
+ * tarball ships no `.sql`. Moved from the Slack service's migrations 001,
+ * 004 and 007 (plans/DISCORD.md DC-004).
+ *
+ * @module portable/hosts/schema
+ */
+import { tablePrefixOf } from './queue';
+/** The shared tables of one host, as one idempotent script. */
+export function hostSchemaSql(tablePrefix) {
+    const p = tablePrefixOf(tablePrefix);
+    return `BEGIN;
+
+CREATE TABLE IF NOT EXISTS ${p}_event_claims (
+  event_id text PRIMARY KEY,
+  claimed_at timestamptz NOT NULL DEFAULT now()
+);
+CREATE INDEX IF NOT EXISTS ${p}_event_claims_claimed_at ON ${p}_event_claims (claimed_at);
+
+CREATE TABLE IF NOT EXISTS ${p}_jobs (
+  id bigserial PRIMARY KEY,
+  payload jsonb NOT NULL,
+  state text NOT NULL DEFAULT 'ready' CHECK (state IN ('ready', 'processing', 'dead')),
+  attempts integer NOT NULL DEFAULT 0,
+  available_at timestamptz NOT NULL DEFAULT now(),
+  locked_at timestamptz,
+  last_error text,
+  created_at timestamptz NOT NULL DEFAULT now()
+);
+CREATE INDEX IF NOT EXISTS ${p}_jobs_ready ON ${p}_jobs (state, available_at, id);
+
+CREATE TABLE IF NOT EXISTS ${p}_usage (
+  usage_key text NOT NULL,
+  usage_window text NOT NULL,
+  used integer NOT NULL DEFAULT 0,
+  PRIMARY KEY (usage_key, usage_window)
+);
+
+CREATE TABLE IF NOT EXISTS ${p}_payload_access (
+  id bigserial PRIMARY KEY,
+  job_id bigint NOT NULL,
+  operator text NOT NULL,
+  reason text NOT NULL,
+  read_at timestamptz NOT NULL DEFAULT now()
+);
+
+CREATE TABLE IF NOT EXISTS ${p}_job_replays (
+  id bigserial PRIMARY KEY,
+  job_id bigint NOT NULL,
+  operator text NOT NULL,
+  replayed boolean NOT NULL,
+  replayed_at timestamptz NOT NULL DEFAULT now()
+);
+
+COMMIT;
+`;
+}
+/** The tables `hostSchemaSql` makes, by name: what a test and an operator check. */
+export function hostTables(tablePrefix) {
+    const p = tablePrefixOf(tablePrefix);
+    return [
+        `${p}_event_claims`,
+        `${p}_jobs`,
+        `${p}_usage`,
+        `${p}_payload_access`,
+        `${p}_job_replays`,
+    ];
+}
+/** Apply the shared tables of one host: idempotent, before the service's own migrations. */
+export async function applyHostSchema(database, tablePrefix) {
+    await database.query(hostSchemaSql(tablePrefix));
+}

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

@@ -0,0 +1,23 @@
+/**
+ * Secrets at rest (SLACK §9, DISCORD §9): AES-256-GCM, each value bound to
+ * what it belongs to (its associated data, an installation's key), with the
+ * key's version kept beside it. Moved from the Slack service
+ * (plans/DISCORD.md DC-004).
+ *
+ * @module portable/hosts/secretCipher
+ */
+export type EncryptedSecret = Readonly<{
+    ciphertext: string;
+    iv: string;
+    keyVersion: number;
+    tag: string;
+}>;
+export declare class SecretCipher {
+    #private;
+    readonly keyVersion: number;
+    constructor(keyBase64: string, keyVersion: number, 
+    /** The setting the key is read from, named when it is refused. */
+    keyName?: string);
+    encrypt(value: string, associatedData: string): EncryptedSecret;
+    decrypt(secret: EncryptedSecret, associatedData: string): string;
+}

package/lib/portable/hosts/secretCipher.js

@@ -0,0 +1,45 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+import { createCipheriv, createDecipheriv, randomBytes } from 'node:crypto';
+export class SecretCipher {
+    keyVersion;
+    #key;
+    constructor(keyBase64, keyVersion, 
+    /** The setting the key is read from, named when it is refused. */
+    keyName = 'The encryption key') {
+        this.keyVersion = keyVersion;
+        this.#key = Buffer.from(keyBase64, 'base64');
+        if (this.#key.length !== 32) {
+            throw new Error(`${keyName} must be a base64-encoded 32-byte key.`);
+        }
+    }
+    encrypt(value, associatedData) {
+        const iv = randomBytes(12);
+        const cipher = createCipheriv('aes-256-gcm', this.#key, iv);
+        cipher.setAAD(Buffer.from(associatedData));
+        const ciphertext = Buffer.concat([
+            cipher.update(value, 'utf8'),
+            cipher.final(),
+        ]);
+        return {
+            ciphertext: ciphertext.toString('base64'),
+            iv: iv.toString('base64'),
+            keyVersion: this.keyVersion,
+            tag: cipher.getAuthTag().toString('base64'),
+        };
+    }
+    decrypt(secret, associatedData) {
+        if (secret.keyVersion !== this.keyVersion) {
+            throw new Error(`No decryption key is configured for version ${secret.keyVersion}.`);
+        }
+        const decipher = createDecipheriv('aes-256-gcm', this.#key, Buffer.from(secret.iv, 'base64'));
+        decipher.setAAD(Buffer.from(associatedData));
+        decipher.setAuthTag(Buffer.from(secret.tag, 'base64'));
+        return Buffer.concat([
+            decipher.update(Buffer.from(secret.ciphertext, 'base64')),
+            decipher.final(),
+        ]).toString('utf8');
+    }
+}

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

@@ -0,0 +1,7 @@
+/**
+ * `<kind>-<40 hex>`: the SHA-256 of the thread's parts joined by `:`, and
+ * `:<generation>` once the thread started over or switched application. The
+ * same parts give the same uid (Slack: app, enterprise or `-`, team,
+ * channel, thread ts; Discord: application, guild, channel, thread).
+ */
+export declare function hostSessionUid(kind: string, parts: readonly string[], generation?: number): string;

package/lib/portable/hosts/sessionUid.js

@@ -0,0 +1,28 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * One host thread is one Datalayer session: its uid, derived from where the
+ * thread is, so that a retry names it again (SLACK §2 rule 2, DISCORD §2
+ * rule 2). Moved from the Slack service (plans/DISCORD.md DC-004).
+ *
+ * @module portable/hosts/sessionUid
+ */
+import { createHash } from 'node:crypto';
+/**
+ * `<kind>-<40 hex>`: the SHA-256 of the thread's parts joined by `:`, and
+ * `:<generation>` once the thread started over or switched application. The
+ * same parts give the same uid (Slack: app, enterprise or `-`, team,
+ * channel, thread ts; Discord: application, guild, channel, thread).
+ */
+export function hostSessionUid(kind, parts, generation) {
+    if (!/^[a-z][a-z0-9-]{1,31}$/.test(kind)) {
+        throw new Error(`A host kind is lowercase letters and digits: ${kind}.`);
+    }
+    if (parts.length === 0 || parts.some(part => part === '')) {
+        throw new Error('A thread is named by its parts, none of them empty.');
+    }
+    const key = `${parts.join(':')}${generation ? `:${generation}` : ''}`;
+    return `${kind}-${createHash('sha256').update(key).digest('hex').slice(0, 40)}`;
+}

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

@@ -0,0 +1,45 @@
+/**
+ * A turn's state as a chat host shows it, from its semantic events: the
+ * answer so far, the tools, the status line, the approvals waited on, the
+ * question it ends on, and how it ended. Each host renders it in its own
+ * blocks (Slack's Block Kit, Discord's components); nothing here is a
+ * host's. Moved from the Slack service (plans/DISCORD.md DC-004).
+ *
+ * @module portable/hosts/turnState
+ */
+import type { AskQuestion, SemanticEvent } from '../semantic';
+export type TurnEnding = 'completion' | 'stop' | 'error';
+export type TurnTool = Readonly<{
+    name: string;
+    status: string;
+}>;
+export type TurnFile = Readonly<{
+    mediaType?: string;
+    name: string;
+    url: string;
+}>;
+export declare class TurnState {
+    #private;
+    /** Whether the turn finished while it streamed: else a `turn.completed` delivery finishes it. */
+    get complete(): boolean;
+    /** Whether the turn ended (answered, stopped, failed) or waits on a question. */
+    get ended(): boolean;
+    /** Whether the turn still runs: not ended, and asking nothing. */
+    get running(): boolean;
+    /** The answer so far, its tables and citations as Markdown. */
+    get answer(): string;
+    /** The question the turn ends on, if any. */
+    get asking(): AskQuestion | undefined;
+    /** The tools whose approval the turn waited on, in order. */
+    get approvals(): readonly string[];
+    /** How the turn ended, if it did. */
+    get ending(): TurnEnding | undefined;
+    /** What the run said when it failed. */
+    get error(): string | undefined;
+    get files(): readonly TurnFile[];
+    /** The status line: what the turn is doing now. */
+    get status(): string;
+    /** Each tool the turn used, by its call, in the order first seen. */
+    get tools(): ReadonlyMap<string, TurnTool>;
+    apply(event: SemanticEvent): void;
+}

package/lib/portable/hosts/turnState.js

@@ -0,0 +1,113 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+export class TurnState {
+    #answer = '';
+    #asking;
+    #approvals = [];
+    #ended;
+    #error;
+    #files = [];
+    #status = 'Working…';
+    #tools = new Map();
+    /** Whether the turn finished while it streamed: else a `turn.completed` delivery finishes it. */
+    get complete() {
+        return this.#ended === 'completion';
+    }
+    /** Whether the turn ended (answered, stopped, failed) or waits on a question. */
+    get ended() {
+        return this.#ended !== undefined || this.#asking !== undefined;
+    }
+    /** Whether the turn still runs: not ended, and asking nothing. */
+    get running() {
+        return !this.ended;
+    }
+    /** The answer so far, its tables and citations as Markdown. */
+    get answer() {
+        return this.#answer;
+    }
+    /** The question the turn ends on, if any. */
+    get asking() {
+        return this.#asking;
+    }
+    /** The tools whose approval the turn waited on, in order. */
+    get approvals() {
+        return this.#approvals;
+    }
+    /** How the turn ended, if it did. */
+    get ending() {
+        return this.#ended;
+    }
+    /** What the run said when it failed. */
+    get error() {
+        return this.#error;
+    }
+    get files() {
+        return this.#files;
+    }
+    /** The status line: what the turn is doing now. */
+    get status() {
+        return this.#status;
+    }
+    /** Each tool the turn used, by its call, in the order first seen. */
+    get tools() {
+        return this.#tools;
+    }
+    apply(event) {
+        switch (event.kind) {
+            case 'text':
+                this.#answer += event.text;
+                break;
+            case 'progress':
+                this.#status = event.label;
+                break;
+            case 'tool':
+                this.#tools.set(event.id || event.name, {
+                    name: event.name,
+                    status: event.status,
+                });
+                this.#status = `${event.status === 'running' ? 'Using' : event.status === 'failed' ? 'Failed:' : 'Used'} ${event.name}`;
+                break;
+            case 'approval':
+                this.#approvals.push(event.toolName);
+                this.#status = `Waiting for approval to use ${event.toolName}`;
+                break;
+            case 'file':
+                this.#files.push({
+                    mediaType: event.mediaType,
+                    name: event.name,
+                    url: event.url,
+                });
+                break;
+            case 'table':
+                this.#answer += `\n\n| ${event.columns.join(' | ')} |\n|${event.columns.map(() => '---').join('|')}|\n${event.rows.map(row => `| ${row.join(' | ')} |`).join('\n')}\n`;
+                break;
+            case 'citation':
+                this.#answer += `\n[${event.title}](${event.url})`;
+                break;
+            case 'ask':
+                this.#asking = event.question;
+                this.#status = 'Waiting for your answer';
+                break;
+            case 'completion':
+                // The streamed words are the answer: a completion's text only
+                // stands in for none, never repeated after them.
+                if (event.text && !this.#answer) {
+                    this.#answer = event.text;
+                }
+                this.#ended = 'completion';
+                this.#status = 'Complete';
+                break;
+            case 'stop':
+                this.#ended = 'stop';
+                this.#status = 'Stopped';
+                break;
+            case 'error':
+                this.#ended = 'error';
+                this.#error = event.message;
+                this.#status = 'Could not finish';
+                break;
+        }
+    }
+}

package/lib/portable/index.d.ts

@@ -9,6 +9,8 @@
 export { messageOfApproval, normalizeApproval, whyAsked, type ApprovalArgs, type ApprovalRecord, type MessageAsked, } from './approvals';
 export { actionOf, APPROVAL_CARD_WORDS, approvalCardOf, argumentsShown, type ApprovalCard, type ApprovalCardProps, type ApprovalCardSource, } from './approvalCard';
 export { AgUiFrames, endsRun, eventsOfStream, NOT_STREAMING, REACTOR_UI_NAME, readRunStream, RUN_CUT_SHORT, toolResultOf, UI_ON_RUN, type AgUiEvent, type ToolResultSaid, } from './agui';
+export { answerParts, isTerminal, SEMANTIC_EVENTS_VERSION, SEMANTIC_KINDS, type AnswerPart, type AskQuestion, type SemanticEvent, type SemanticKind, } from './semantic';
+export { askQuestionOf, semanticOf, turnOf, type TurnInfo, } from './semanticOfAgUi';
 export { AG_UI_NOT_ALLOWED, AG_UI_NOT_ON_RUNTIME, agUiRefusal, refusalBody, refusalDetail, } from './agUiRefusal';
 export { ASKED_FOR_TAG, askedOf, RUN_END_WORDS } from './records';
 export { messagesOfThread, openThread, snapshotOfStream, THREAD_WORDS, } from './thread';

package/lib/portable/index.js

@@ -15,6 +15,9 @@ export { messageOfApproval, normalizeApproval, whyAsked, } from './approvals';
 export { actionOf, APPROVAL_CARD_WORDS, approvalCardOf, argumentsShown, } from './approvalCard';
 // A run's stream, read as every client reads it.
 export { AgUiFrames, endsRun, eventsOfStream, NOT_STREAMING, REACTOR_UI_NAME, readRunStream, RUN_CUT_SHORT, toolResultOf, UI_ON_RUN, } from './agui';
+// A run's stream reduced to what a chat host shows (DISCORD DC-005, SLACK S-205).
+export { answerParts, isTerminal, SEMANTIC_EVENTS_VERSION, SEMANTIC_KINDS, } from './semantic';
+export { askQuestionOf, semanticOf, turnOf, } from './semanticOfAgUi';
 export { AG_UI_NOT_ALLOWED, AG_UI_NOT_ON_RUNTIME, agUiRefusal, refusalBody, refusalDetail, } from './agUiRefusal';
 // The record's words, and a person's conversation read again.
 export { ASKED_FOR_TAG, askedOf, RUN_END_WORDS } from './records';