@datalayer/agent-runtimes 1.5.45 → 1.5.46

package/lib/portable/hosts/contracts.js

@@ -0,0 +1,235 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+import { createHmac, timingSafeEqual } from 'node:crypto';
+import { z } from 'zod';
+/**
+ * The generic Datalayer host contracts (plans/SLACK.md §4.3, plans/DISCORD.md
+ * §4.3), as ai-agents answers them, for every chat host (Slack, Discord).
+ * These shapes are shared with ai-agents through `contracts.json`, beside
+ * this file and byte-identical to ai-agents' `tests/fixtures/hosts/`, which
+ * both sides test. A delivery's `target` stays opaque here: each host
+ * validates its own.
+ *
+ * @module portable/hosts/contracts
+ */
+export const HOST_KEY_HEADER = 'X-Datalayer-Host-Key';
+export const SIGNATURE_HEADER = 'X-Datalayer-Signature';
+export const TIMESTAMP_HEADER = 'X-Datalayer-Timestamp';
+export const DELIVERY_HEADER = 'X-Datalayer-Delivery';
+export const IDEMPOTENCY_HEADER = 'Idempotency-Key';
+/** The presentation version the hosts render; another is reviewed in Datalayer. */
+export const PRESENTATION_VERSION = 1;
+export const bindSchema = z.object({
+    host: z
+        .object({
+        uid: z.string().min(1),
+        state: z.string(),
+        name: z.string().optional(),
+        default_deployment: z.string().optional(),
+    })
+        .loose(),
+    host_key: z.string().startsWith('dlhk_'),
+});
+/** What a link code is redeemed at: the landing's confirm page. */
+export const LINK_PAGE_PATH = '/hosts/link';
+/**
+ * `GET /apps/hosts/self`: the installation with its allowed deployments.
+ * `channels`, `direct_only` and `paused` are the installation's channel
+ * policy and pause (S-104, S-105, S-403).
+ */
+export const selfSchema = z.object({
+    host: z
+        .object({
+        uid: z.string().min(1),
+        account_uid: z.string().optional(),
+        default_deployment: z.string().optional(),
+        deployments: z.array(z
+            .object({
+            uid: z.string().min(1),
+            app_name: z.string().optional(),
+            kept: z.boolean().optional(),
+        })
+            .loose()),
+        channels: z
+            .array(z.object({
+            id: z.string().min(1),
+            state: z.enum(['allow', 'deny']),
+            deployment: z.string().optional(),
+        }))
+            .optional(),
+        direct_only: z.array(z.string()).optional(),
+        paused: z.boolean().optional(),
+    })
+        .loose(),
+});
+/** `POST /apps/hosts/handoffs`: a one-use code that opens one session or approval (S-305). */
+export const handoffSchema = z.object({
+    code: z.string().startsWith('dlho_'),
+    expires_in: z.number().int().nonnegative(),
+    path: z.string().startsWith('/hosts/open?code='),
+});
+export const linkStateSchema = z.object({
+    linked: z.boolean(),
+    principal_uid: z.string().optional(),
+});
+export const webhookSchema = z.object({
+    url: z.url(),
+    events: z.array(z.string()),
+    version: z.number().int(),
+    signing_secret: z.string().min(32),
+});
+/** One delivery of the outbox, as `GET …/self/deliveries` lists it. */
+export const outboxItemSchema = z
+    .object({
+    uid: z.string().min(1),
+    event: z.string(),
+    payload: z.record(z.string(), z.unknown()),
+    state: z.string(),
+})
+    .loose();
+export const decisionSchema = z.object({
+    approval: z
+        .object({ id: z.string().nullable().optional(), status: z.string() })
+        .loose(),
+});
+export const linkCodeSchema = z.object({
+    code: z.string().startsWith('dlhc_'),
+    expires_in: z.number().int().nonnegative(),
+    confirm: z.string(),
+});
+export const exchangeSchema = z.object({
+    access_token: z.string().min(1),
+    token_type: z.literal('Bearer'),
+    expires_in: z.number().int().nonnegative(),
+    exp: z.number().int(),
+    principal_uid: z.string().min(1),
+    host_uid: z.string().min(1),
+    deployment: z.object({
+        uid: z.string().min(1),
+        app_uid: z.string(),
+        app_name: z.string(),
+        version: z.number().int(),
+    }),
+    session_api: z.object({ url: z.url(), agent: z.string() }),
+    user_token: z.string().optional(),
+});
+const fieldSchema = z.object({
+    name: z.string(),
+    label: z.string(),
+    value: z.string(),
+});
+export const presentationSchema = z.object({
+    version: z.number().int(),
+    approval_id: z.string().min(1),
+    status: z.string(),
+    owner_uid: z.string(),
+    tool_name: z.string(),
+    action_class: z.enum([
+        'read',
+        'send',
+        'write',
+        'execute',
+        'publish',
+        'delete',
+        'financial',
+        'unknown',
+    ]),
+    session_uid: z.string(),
+    created_at: z.string().nullable().optional(),
+    expires_at: z.string().nullable().optional(),
+    fields: z.array(fieldSchema),
+    arguments: z.record(z.string(), z.unknown()),
+    secret_fields: z.array(z.string()),
+    complete: z.boolean(),
+    host_may_decide: z.boolean(),
+    reasons: z.array(z.string()),
+    digest: z.string().regex(/^[0-9a-f]{64}$/),
+});
+export const deliverySchema = z.discriminatedUnion('event', [
+    z.object({
+        delivery: z.string().min(1),
+        event: z.literal('approval.requested'),
+        payload: z
+            .object({
+            approval_id: z.string().min(1),
+            tool_name: z.string(),
+            presentation: z.string(),
+            session_uid: z.string(),
+            deployment_uid: z.string(),
+            target: z.record(z.string(), z.unknown()),
+        })
+            .loose(),
+    }),
+    z.object({
+        delivery: z.string().min(1),
+        event: z.literal('approval.decided'),
+        payload: z
+            .object({
+            approval_id: z.string().min(1),
+            status: z.string(),
+            decided_by: z.string(),
+            session_uid: z.string(),
+            deployment_uid: z.string(),
+            target: z.record(z.string(), z.unknown()),
+        })
+            .loose(),
+    }),
+    z.object({
+        delivery: z.string().min(1),
+        event: z.literal('turn.completed'),
+        payload: z
+            .object({
+            record_entry: z.string(),
+            session_uid: z.string(),
+            deployment_uid: z.string(),
+            target: z.record(z.string(), z.unknown()),
+        })
+            .loose(),
+    }),
+]);
+/** An outbox item read as the delivery a push would have carried. */
+export function deliveryOfOutbox(item) {
+    const { uid, event, payload } = outboxItemSchema.parse(item);
+    return deliverySchema.parse({ delivery: uid, event, payload });
+}
+/**
+ * Whether a host may offer Approve and Reject: only what the server says a
+ * host may decide, in a version the hosts render, shown whole, pending, with
+ * no secret field. Anything else gets *Review in Datalayer* (SLACK §2 rule 6,
+ * DISCORD §2 rule 6). Each host also checks the card fits its own limits.
+ */
+export function hostMayDecide(presentation) {
+    return (presentation.version === PRESENTATION_VERSION &&
+        presentation.host_may_decide &&
+        presentation.complete &&
+        presentation.secret_fields.length === 0 &&
+        presentation.status === 'pending');
+}
+/** `v1=` HMAC-SHA256 of `"<timestamp>.<raw body>"`, as ai-agents signs a push. */
+export function deliverySignature(secret, timestamp, rawBody) {
+    const mac = createHmac('sha256', secret);
+    mac.update(`${timestamp}.`);
+    mac.update(rawBody);
+    return `v1=${mac.digest('hex')}`;
+}
+/**
+ * Verify a pushed delivery before trusting it: its signature in constant
+ * time, and a timestamp within five minutes, so a captured push cannot be
+ * replayed later.
+ */
+export function verifyDelivery(input) {
+    const stamp = Number(input.timestamp);
+    const now = input.nowSeconds ?? Math.floor(Date.now() / 1000);
+    if (!Number.isInteger(stamp) ||
+        Math.abs(now - stamp) > (input.toleranceSeconds ?? 300)) {
+        throw new Error("The delivery's timestamp is missing or too old.");
+    }
+    const expected = Buffer.from(deliverySignature(input.secret, stamp, input.rawBody));
+    const given = Buffer.from(input.signature ?? '');
+    if (expected.length !== given.length || !timingSafeEqual(expected, given)) {
+        throw new Error("The delivery's signature does not match.");
+    }
+    return deliverySchema.parse(JSON.parse(input.rawBody.toString()));
+}

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