@datalayer/agent-runtimes 1.5.44 → 1.5.46

package/lib/portable/hosts/contracts.json

@@ -0,0 +1,381 @@
+{
+  "version": 1,
+  "about": "The generic host contracts of plans/SLACK.md §4.3, as ai-agents and the runtime's session API answer them. Shared verbatim by ai-agents (tests/fixtures/hosts) and the Slack adapter (tech/datalayer/slack, test/contracts): each side's tests check its half against this file.",
+  "headers": {
+    "host_key": "X-Datalayer-Host-Key",
+    "signature": "X-Datalayer-Signature",
+    "timestamp": "X-Datalayer-Timestamp",
+    "delivery": "X-Datalayer-Delivery",
+    "idempotency_key": "Idempotency-Key"
+  },
+  "routes": {
+    "bind": "POST /api/ai-agents/v1/apps/hosts/bind",
+    "self": "GET /api/ai-agents/v1/apps/hosts/self",
+    "uninstalled": "DELETE /api/ai-agents/v1/apps/hosts/self",
+    "link_code": "POST /api/ai-agents/v1/apps/hosts/self/link-codes",
+    "link_state": "GET /api/ai-agents/v1/apps/hosts/self/links/{external_user_id}",
+    "unlink": "DELETE /api/ai-agents/v1/apps/hosts/self/links/{external_user_id}",
+    "exchange": "POST /api/ai-agents/v1/apps/hosts/self/token",
+    "webhook": "PUT /api/ai-agents/v1/apps/hosts/self/delivery",
+    "outbox": "GET /api/ai-agents/v1/apps/hosts/self/deliveries",
+    "ack": "POST /api/ai-agents/v1/apps/hosts/self/deliveries/{delivery_uid}/ack",
+    "bind_session": "PUT /api/ai-agents/v1/apps/hosts/sessions/{session_uid}",
+    "whoami": "GET /api/ai-agents/v1/apps/hosts/whoami",
+    "presentation": "GET /api/ai-agents/v1/tool-approvals/{approval_id}/presentation",
+    "decision": "POST /api/ai-agents/v1/apps/hosts/approvals/{approval_id}/decision",
+    "start_session": "POST {session_api.url}",
+    "send_message": "POST {session_api.url}/{session_uid}/messages",
+    "confirm_link": "POST /api/ai-agents/v1/apps/hosts/links",
+    "preview_link": "GET /api/ai-agents/v1/apps/hosts/links/preview?code={code}",
+    "change_host": "PATCH /api/ai-agents/v1/apps/hosts/{uid}",
+    "handoff": "POST /api/ai-agents/v1/apps/hosts/handoffs",
+    "redeem_handoff": "POST /api/ai-agents/v1/apps/hosts/handoffs/redeem"
+  },
+  "bind": {
+    "request": {
+      "code": "dlhc_…",
+      "external_id": "A0123:-:T0123",
+      "name": "Acme"
+    },
+    "response_keys": [
+      "success",
+      "host",
+      "host_key"
+    ]
+  },
+  "link_code": {
+    "request": {
+      "external_user_id": "U0ALICE",
+      "external_user_name": "Alice"
+    },
+    "response_keys": [
+      "success",
+      "code",
+      "expires_in",
+      "confirm"
+    ]
+  },
+  "exchange": {
+    "request": {
+      "external_user_id": "U0ALICE",
+      "deployment_uid": "dep-1"
+    },
+    "response_keys": [
+      "success",
+      "access_token",
+      "token_type",
+      "expires_in",
+      "exp",
+      "principal_uid",
+      "host_uid",
+      "deployment",
+      "session_api"
+    ],
+    "deployment_keys": [
+      "uid",
+      "app_uid",
+      "app_name",
+      "version"
+    ],
+    "session_api_keys": [
+      "url",
+      "agent"
+    ],
+    "optional_keys": [
+      "user_token"
+    ],
+    "token_claims": [
+      "jti",
+      "iss",
+      "iat",
+      "exp",
+      "aud",
+      "sub",
+      "azp",
+      "host_kind",
+      "link",
+      "deployment_uid",
+      "app_uid",
+      "scope"
+    ],
+    "audience": "datalayer:app:host",
+    "max_ttl_seconds": 900,
+    "optional_request": {
+      "place": {
+        "kind": "channel",
+        "id": "C0"
+      }
+    },
+    "place_kinds": [
+      "channel",
+      "direct"
+    ]
+  },
+  "whoami": {
+    "response_keys": [
+      "success",
+      "sub",
+      "azp",
+      "host_kind",
+      "deployment_uid",
+      "app_uid",
+      "link",
+      "scope",
+      "expires_in"
+    ]
+  },
+  "external_turn": {
+    "start_request": {
+      "agent": "agent-desk",
+      "deployment_uid": "dep-1",
+      "opener": "Summarize the launch risks",
+      "session": "slack-T0-C0-1700000000-000001",
+      "external_event_id": "Ev0123",
+      "user_token": ""
+    },
+    "message_request": {
+      "text": "And the costs?",
+      "external_event_id": "Ev0124"
+    },
+    "turn_event": {
+      "type": "CUSTOM",
+      "name": "loop.turn",
+      "value_keys": [
+        "turn",
+        "external_event_id",
+        "replayed",
+        "state"
+      ]
+    },
+    "replay": "The same Idempotency-Key (or, without one, the same external_event_id) and the same request answer the original session and turn with replayed=true, and run nothing; the same key with another request is 409."
+  },
+  "webhook": {
+    "request": {
+      "url": "https://slack.example/datalayer/deliveries",
+      "events": [
+        "approval.requested",
+        "approval.decided",
+        "turn.completed"
+      ]
+    },
+    "response_keys": [
+      "success",
+      "url",
+      "events",
+      "version",
+      "signing_secret"
+    ]
+  },
+  "delivery": {
+    "events": [
+      "approval.requested",
+      "approval.decided",
+      "turn.completed"
+    ],
+    "payload_keys": {
+      "approval.requested": [
+        "approval_id",
+        "tool_name",
+        "presentation",
+        "session_uid",
+        "deployment_uid",
+        "target"
+      ],
+      "approval.decided": [
+        "approval_id",
+        "status",
+        "decided_by",
+        "session_uid",
+        "deployment_uid",
+        "target"
+      ],
+      "turn.completed": [
+        "record_entry",
+        "session_uid",
+        "deployment_uid",
+        "target"
+      ]
+    },
+    "signing": {
+      "secret": "contract-signing-secret",
+      "timestamp": 1700000000,
+      "body": "{\"delivery\":\"d0c1\",\"event\":\"approval.requested\",\"payload\":{\"approval_id\":\"ap-1\",\"tool_name\":\"send_email\",\"presentation\":\"/api/ai-agents/v1/tool-approvals/ap-1/presentation\",\"session_uid\":\"slack-T0-C0-1700000000-000001\",\"deployment_uid\":\"dep-1\",\"target\":{\"channel\":\"C0\",\"thread_ts\":\"1700000000.000001\"}}}",
+      "signature": "v1=35630034244d3edab52b937cf4437542ec87958014351d587806b267f805b05f",
+      "rule": "v1= HMAC-SHA256(secret, \"<timestamp>.<raw body>\") in hex"
+    }
+  },
+  "presentation": {
+    "version": 1,
+    "response_keys": [
+      "success",
+      "presentation"
+    ],
+    "keys": [
+      "version",
+      "approval_id",
+      "status",
+      "owner_uid",
+      "tool_name",
+      "action_class",
+      "session_uid",
+      "created_at",
+      "expires_at",
+      "fields",
+      "arguments",
+      "secret_fields",
+      "complete",
+      "host_may_decide",
+      "reasons",
+      "digest"
+    ],
+    "action_classes": [
+      "read",
+      "send",
+      "write",
+      "execute",
+      "publish",
+      "delete",
+      "financial",
+      "unknown"
+    ],
+    "host_decidable": [
+      "read",
+      "send",
+      "write"
+    ],
+    "example": {
+      "version": 1,
+      "approval_id": "ap-1",
+      "status": "pending",
+      "owner_uid": "alice",
+      "tool_name": "send_email",
+      "action_class": "send",
+      "session_uid": "slack-T0-C0-1700000000-000001",
+      "created_at": "2026-10-07T10:00:00Z",
+      "expires_at": null,
+      "fields": [
+        {
+          "name": "to",
+          "label": "To",
+          "value": "release@example.com"
+        },
+        {
+          "name": "subject",
+          "label": "Subject",
+          "value": "Launch decision"
+        },
+        {
+          "name": "body",
+          "label": "Body",
+          "value": "We go with option B."
+        }
+      ],
+      "arguments": {
+        "to": "release@example.com",
+        "subject": "Launch decision",
+        "body": "We go with option B."
+      },
+      "secret_fields": [],
+      "complete": true,
+      "host_may_decide": true,
+      "reasons": [],
+      "digest": "0000000000000000000000000000000000000000000000000000000000000000"
+    }
+  },
+  "decision": {
+    "request": {
+      "approve": true,
+      "digest": "<presentation.digest>",
+      "note": null
+    },
+    "response_keys": [
+      "success",
+      "approval"
+    ]
+  },
+  "self": {
+    "host_keys": [
+      "uid",
+      "state",
+      "deployments",
+      "default_deployment",
+      "channels",
+      "direct_only",
+      "paused"
+    ],
+    "deployment_keys": [
+      "uid",
+      "app_uid",
+      "app_name",
+      "state",
+      "kept"
+    ]
+  },
+  "preview": {
+    "response_keys": [
+      "success",
+      "host",
+      "deployments",
+      "external_user_id",
+      "external_user_name",
+      "expires_in"
+    ],
+    "deployment_keys": [
+      "uid",
+      "app_name",
+      "default"
+    ]
+  },
+  "change_host": {
+    "request": {
+      "channels": [
+        {
+          "id": "C0",
+          "state": "deny"
+        },
+        {
+          "id": "C1",
+          "state": "allow",
+          "deployment": "dep-1"
+        }
+      ],
+      "direct_only": [
+        "dep-1"
+      ],
+      "paused": false
+    }
+  },
+  "handoff": {
+    "request": {
+      "kind": "approval",
+      "target": "ap-1"
+    },
+    "kinds": [
+      "session",
+      "approval"
+    ],
+    "response_keys": [
+      "success",
+      "code",
+      "expires_in",
+      "path"
+    ],
+    "code_prefix": "dlho_",
+    "redeem_request": {
+      "code": "dlho_…"
+    },
+    "redeem_response_keys": [
+      "success",
+      "kind",
+      "target",
+      "deployment_uid",
+      "path"
+    ],
+    "refusals": {
+      "unauthenticated": 401,
+      "another_account": 403,
+      "expired": 410,
+      "spent_or_unknown": 404
+    }
+  }
+}

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

@@ -0,0 +1,41 @@
+import { Logger } from './observability';
+import { PostgresWorkQueue } from './postgresQueue';
+import { type ConnectionPool } from './queue';
+export type DeadLetter = Readonly<{
+    id: string;
+    kind: string;
+    attempts: number;
+    createdAt: string;
+    /** The last error, redacted: a credential in an error message is not shown. */
+    lastError: string;
+    /** sha256 of the payload: tells two jobs apart without showing either. */
+    payloadHash: string;
+}>;
+export declare function payloadHash(payload: unknown): string;
+export declare class DeadLetters {
+    #private;
+    readonly database: ConnectionPool;
+    readonly queue: PostgresWorkQueue<unknown>;
+    readonly logger: Logger;
+    constructor(database: ConnectionPool, queue: PostgresWorkQueue<unknown>, logger?: Logger);
+    list(limit?: number): Promise<DeadLetter[]>;
+    replay(id: string, operator: string): Promise<boolean>;
+    /** A payload, for a stated reason, recorded and audited; secrets still redacted. */
+    payload(id: string, operator: string, reason: string): Promise<unknown>;
+}
+/** The dead letters of a host's queue (`<prefix>_jobs`). */
+export declare function deadLetters(database: ConnectionPool, tablePrefix: string, logger?: Logger): DeadLetters;
+/** What the dead-letters bin prints or says, and its exit code. */
+export type CliOutput = {
+    table: (rows: unknown) => void;
+    info: (line: string) => void;
+    error: (line: string) => void;
+};
+export declare const DEAD_LETTERS_USAGE = "Usage: dead-letters list | replay <id> | payload <id> <reason>";
+/**
+ * `dead-letters list | replay <id> | payload <id> <reason…>`: metadata and
+ * hashes by default (S-405). Who acts is said in `operator`
+ * (`DATALAYER_OPERATOR`), never taken from the container's user: a replay
+ * and a payload read are kept with this name. Answers the exit code.
+ */
+export declare function runDeadLettersCli(letters: DeadLetters, argv: readonly string[], operator: string, out?: CliOutput): Promise<number>;

package/lib/portable/hosts/deadLetters.js

@@ -0,0 +1,124 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * Dead letters (SLACK §9, S-405; DISCORD DC-403): jobs that failed five
+ * times. By default an operator sees their metadata and a hash of their
+ * payload — never the words of a prompt or a delivery. Replaying puts one
+ * back to work, once. Reading a payload is privileged: a dead job's only, it
+ * needs a reason, is recorded in `<prefix>_payload_access` and audited, and
+ * its credentials are still redacted. Every replay is kept in
+ * `<prefix>_job_replays` with who asked. Moved from the Slack service
+ * (plans/DISCORD.md DC-004); each service keeps only the bin that opens its
+ * database and calls `runDeadLettersCli`.
+ *
+ * @module portable/hosts/deadLetters
+ */
+import { createHash } from 'node:crypto';
+import { Logger, redact, redactCredentials } from './observability';
+import { PostgresWorkQueue } from './postgresQueue';
+import { tablePrefixOf } from './queue';
+export function payloadHash(payload) {
+    return createHash('sha256').update(JSON.stringify(payload)).digest('hex');
+}
+export class DeadLetters {
+    database;
+    queue;
+    logger;
+    #access;
+    #queueName;
+    constructor(database, queue, logger = new Logger()) {
+        this.database = database;
+        this.queue = queue;
+        this.logger = logger;
+        const prefix = tablePrefixOf(queue.tablePrefix);
+        this.#access = `${prefix}_payload_access`;
+        this.#queueName = `${prefix}-queue`;
+    }
+    async list(limit = 50) {
+        const dead = await this.queue.dead(limit);
+        return Promise.all(dead.map(async (one) => ({
+            attempts: one.attempts,
+            createdAt: one.createdAt,
+            id: one.id,
+            kind: one.kind,
+            lastError: String(redact(one.lastError ?? '')),
+            payloadHash: payloadHash(await this.queue.payloadOf(one.id)),
+        })));
+    }
+    async replay(id, operator) {
+        if (!operator.trim()) {
+            throw new Error('Name who replays the job.');
+        }
+        const replayed = await this.queue.replay(id, operator);
+        this.logger.audit('admin.changed', {
+            by: operator,
+            installation: this.#queueName,
+            job: id,
+            reason: replayed ? 'dead job replayed' : 'not a dead job',
+        });
+        return replayed;
+    }
+    /** A payload, for a stated reason, recorded and audited; secrets still redacted. */
+    async payload(id, operator, reason) {
+        if (reason.trim().length < 10) {
+            throw new Error('Say why the payload is read: ten characters at least.');
+        }
+        if (!operator.trim()) {
+            throw new Error('Name who reads the payload.');
+        }
+        // A dead job's only: a live job or an unknown id is refused, and no read
+        // of it is recorded.
+        const payload = await this.queue.payloadOf(id);
+        if (payload === undefined) {
+            throw new Error(`Job ${id} is not a dead job: there is no payload to read.`);
+        }
+        await this.database.query(`INSERT INTO ${this.#access} (job_id, operator, reason) VALUES ($1, $2, $3)`, [id, operator, reason.slice(0, 1_000)]);
+        this.logger.audit('payload.read', {
+            by: operator,
+            installation: this.#queueName,
+            job: id,
+            reason: 'privileged payload access',
+        });
+        return redactCredentials(payload);
+    }
+}
+/** The dead letters of a host's queue (`<prefix>_jobs`). */
+export function deadLetters(database, tablePrefix, logger) {
+    return new DeadLetters(database, new PostgresWorkQueue(database, tablePrefix), logger);
+}
+export const DEAD_LETTERS_USAGE = 'Usage: dead-letters list | replay <id> | payload <id> <reason>';
+/**
+ * `dead-letters list | replay <id> | payload <id> <reason…>`: metadata and
+ * hashes by default (S-405). Who acts is said in `operator`
+ * (`DATALAYER_OPERATOR`), never taken from the container's user: a replay
+ * and a payload read are kept with this name. Answers the exit code.
+ */
+export async function runDeadLettersCli(letters, argv, operator, out = {
+    table: rows => console.table(rows),
+    info: line => console.info(line),
+    error: line => console.error(line),
+}) {
+    const [command, id, ...rest] = argv;
+    if (!operator.trim()) {
+        out.error('DATALAYER_OPERATOR is required: the name kept with every replay and payload read.');
+        return 1;
+    }
+    if (command === 'list') {
+        out.table(await letters.list());
+        return 0;
+    }
+    if (command === 'replay' && id) {
+        out.info((await letters.replay(id, operator))
+            ? `Job ${id} is back to work.`
+            : `Job ${id} is not a dead job.`);
+        return 0;
+    }
+    if (command === 'payload' && id) {
+        out.info(JSON.stringify(await letters.payload(id, operator, rest.join(' ')), null, 2));
+        return 0;
+    }
+    out.error(DEAD_LETTERS_USAGE);
+    return 1;
+}

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

@@ -0,0 +1,76 @@
+/**
+ * Datalayer's deliveries to a chat host (SLACK §4.3, 3; DISCORD §3.8): the
+ * signed webhook ai-agents pushes to, the outbox read when a push was
+ * missed, and each delivery handled once then acknowledged. What a delivery
+ * shows is the host's own (its `DeliveryHandler`); where its installations
+ * and claims are kept is its store, seen here as a `DeliverySink` and a
+ * `DeliveryClaimStore`. Moved from the Slack service (plans/DISCORD.md
+ * DC-004).
+ *
+ * @module portable/hosts/deliveries
+ */
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import type { DatalayerHostClient } from './client';
+import { type HostDelivery } from './contracts';
+/** Where Datalayer pushes an installation's deliveries, under the service's public address. */
+export declare const DELIVERY_PATH = "/datalayer/deliveries";
+export declare const DELIVERY_ROUTE = "/datalayer/deliveries/:hostUid";
+export type DeliveryJob = Readonly<{
+    delivery: HostDelivery;
+    hostUid: string;
+}>;
+/** A host installation bound at Datalayer: its uid and key. */
+export type BoundHostKey = Readonly<{
+    hostKey: string;
+    hostUid: string;
+}>;
+/** Where a host keeps its installations, as deliveries read them. */
+export interface DeliverySink {
+    /** What Datalayer signs an installation's pushes with, or `undefined` for an unknown one. */
+    deliverySecretOf(hostUid: string): Promise<string | undefined>;
+    /** The installation's key, or `undefined` once it was removed (late work is dropped). */
+    hostKeyOf(hostUid: string): Promise<string | undefined>;
+    /** Every installation bound at Datalayer: whose outbox is read. */
+    boundHosts(): Promise<readonly BoundHostKey[]>;
+}
+/** Where a host keeps what it handled once: a claim taken, or released when handling failed. */
+export interface DeliveryClaimStore {
+    claimEvent(id: string): Promise<boolean>;
+    releaseEvent(id: string): Promise<void>;
+}
+/**
+ * Handle one delivery of an installation once (claimed by its uid), then
+ * acknowledge it at Datalayer. A removed installation's delivery is dropped;
+ * a handling that fails releases its claim, so the queue tries again.
+ */
+export declare function receiveDelivery(job: DeliveryJob, input: {
+    sink: DeliverySink;
+    claims: DeliveryClaimStore;
+    client: Pick<DatalayerHostClient, 'acknowledge'>;
+    handle: (delivery: HostDelivery) => Promise<void>;
+}): Promise<void>;
+/**
+ * The signed webhook Datalayer pushes to (`POST /datalayer/deliveries/{host}`,
+ * registered with `PUT …/self/delivery`): verified with that installation's
+ * secret — HMAC over `<timestamp>.<body>`, five minutes at most — then queued
+ * and acknowledged with 2xx at once; the work runs from the queue.
+ */
+export declare function deliveryRoute(sink: Pick<DeliverySink, 'deliverySecretOf'>, enqueue: (job: DeliveryJob) => Promise<void>, nowSeconds?: () => number): (request: IncomingMessage & {
+    params?: Record<string, string | string[]>;
+}, response: ServerResponse) => Promise<void>;
+/**
+ * The outbox, read when a push was missed or no address is registered
+ * (`GET …/self/deliveries`): each delivery of every bound installation
+ * queued, handled once, then acknowledged.
+ */
+export declare class DeliveryPoller {
+    #private;
+    readonly sink: Pick<DeliverySink, 'boundHosts'>;
+    readonly client: Pick<DatalayerHostClient, 'outbox'>;
+    readonly enqueue: (job: DeliveryJob) => Promise<void>;
+    readonly logger: Pick<Console, 'warn'>;
+    constructor(sink: Pick<DeliverySink, 'boundHosts'>, client: Pick<DatalayerHostClient, 'outbox'>, enqueue: (job: DeliveryJob) => Promise<void>, logger?: Pick<Console, 'warn'>);
+    pollOnce(): Promise<number>;
+    start(intervalSeconds: number): void;
+    stop(): void;
+}