@datalayer/agent-runtimes 1.5.45 → 1.5.46

package/lib/portable/hosts/approvalRenderers.js

@@ -0,0 +1,180 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/** Action classes that are decided in Datalayer only (§15, 5). */
+export const DATALAYER_ONLY = new Set([
+    'delete',
+    'publish',
+    'financial',
+    'execute',
+    'unknown',
+]);
+const text = (value) => typeof value === 'string' ? value : JSON.stringify(value, null, 2);
+const list = (value) => Array.isArray(value) ? value.map(text).join(', ') : text(value);
+/** The arguments a renderer did not account for: each fails the card closed. */
+function unknownKeys(presentation, known) {
+    return Object.keys(presentation.arguments).filter(key => !known.includes(key));
+}
+function rendered(name, presentation, fields, known, extra = []) {
+    const unknown = unknownKeys(presentation, known);
+    const reasons = [
+        ...extra,
+        ...(unknown.length
+            ? [
+                `@Datalayer does not know how to show ${unknown.join(', ')} of this action: review it in Datalayer.`,
+            ]
+            : []),
+    ];
+    return { complete: reasons.length === 0, fields, reasons, renderer: name };
+}
+const MAIL_TOOL = /(^|[_.-])(send|draft)[_.-]?(e?mail|message)($|[_.-])|^gmail[_.-]send|^mail[_.-]send$/i;
+const MAIL_KEYS = [
+    'to',
+    'cc',
+    'bcc',
+    'subject',
+    'body',
+    'html',
+    'attachments',
+    'reply_to',
+];
+/** Mail: every recipient, the subject, the whole body; an attachment goes to Datalayer. */
+const mail = {
+    name: 'mail',
+    matches: presentation => presentation.action_class === 'send' &&
+        MAIL_TOOL.test(presentation.tool_name),
+    render(presentation) {
+        const args = presentation.arguments;
+        const fields = [];
+        const missing = [];
+        const extra = [];
+        for (const [key, label] of [
+            ['to', 'To'],
+            ['cc', 'Cc'],
+            ['bcc', 'Bcc'],
+            ['reply_to', 'Reply to'],
+            ['subject', 'Subject'],
+        ])
+            if (args[key] !== undefined && args[key] !== null && args[key] !== '')
+                fields.push({ label, value: list(args[key]) });
+        if (args.to === undefined || args.to === '' || args.to === null)
+            missing.push('its recipients');
+        if (args.subject === undefined)
+            missing.push('its subject');
+        if (args.html !== undefined && args.html !== null && args.html !== '')
+            extra.push('It sends formatted mail, which a chat cannot show as it will be read: review it in Datalayer.');
+        if (args.body === undefined && args.html === undefined)
+            missing.push('its body');
+        else if (args.body !== undefined)
+            fields.push({ label: 'Body', value: text(args.body) });
+        const attachments = Array.isArray(args.attachments)
+            ? args.attachments
+            : args.attachments
+                ? [args.attachments]
+                : [];
+        if (attachments.length > 0) {
+            fields.push({ label: 'Attachments', value: list(attachments) });
+            extra.push('It sends attachments, which are reviewed in Datalayer, where you can open them.');
+        }
+        if (missing.length)
+            extra.push(`The request does not say ${missing.join(', ')}: review it in Datalayer.`);
+        return rendered('mail', presentation, fields, MAIL_KEYS, extra);
+    },
+};
+const WRITE_TOOL = /(^|[_.-])(write|update|edit|append|create|save|set|rename|move)[_.-]?/i;
+const WRITE_KEYS = [
+    'path',
+    'file',
+    'filename',
+    'name',
+    'title',
+    'content',
+    'text',
+    'new_path',
+    'destination',
+    'mode',
+];
+/** A write: where, and the whole of what is written. */
+const write = {
+    name: 'write',
+    matches: presentation => presentation.action_class === 'write' &&
+        WRITE_TOOL.test(presentation.tool_name),
+    render(presentation) {
+        const args = presentation.arguments;
+        const fields = [];
+        for (const [key, label] of [
+            ['path', 'Where'],
+            ['file', 'Where'],
+            ['filename', 'Where'],
+            ['name', 'Name'],
+            ['title', 'Title'],
+            ['new_path', 'Moved to'],
+            ['destination', 'Moved to'],
+            ['mode', 'How'],
+            ['content', 'What is written'],
+            ['text', 'What is written'],
+        ])
+            if (args[key] !== undefined)
+                fields.push({ label, value: text(args[key]) });
+        const extra = fields.length === 0
+            ? ['The request does not say what it writes: review it in Datalayer.']
+            : [];
+        return rendered('write', presentation, fields, WRITE_KEYS, extra);
+    },
+};
+/** Delete, publish, money and running code: shown, decided only in Datalayer (§15, 5). */
+const datalayerOnly = {
+    name: 'datalayer-only',
+    matches: presentation => DATALAYER_ONLY.has(presentation.action_class),
+    render(presentation) {
+        const words = {
+            delete: 'Deleting is decided in Datalayer.',
+            execute: 'Running code is decided in Datalayer.',
+            financial: 'Moving money is decided in Datalayer.',
+            publish: 'Publishing is decided in Datalayer.',
+            unknown: '@Datalayer does not know this action: it is decided in Datalayer.',
+        };
+        return {
+            complete: false,
+            fields: presentation.fields.map(({ label, value }) => ({ label, value })),
+            reasons: [
+                words[presentation.action_class] ?? 'It is decided in Datalayer.',
+            ],
+            renderer: 'datalayer-only',
+        };
+    },
+};
+/** A read: every argument, by its name, whole — nothing is changed or sent. */
+const read = {
+    name: 'read',
+    matches: presentation => presentation.action_class === 'read',
+    render(presentation) {
+        const fields = Object.entries(presentation.arguments).map(([key, value]) => ({ label: key, value: text(value) }));
+        return rendered('read', presentation, fields, Object.keys(presentation.arguments));
+    },
+};
+/** The renderers, the first that matches wins: Datalayer-only before any other. */
+export const RENDERERS = [
+    datalayerOnly,
+    mail,
+    write,
+    read,
+];
+/**
+ * How a host shows an approval, by the renderer that knows its tool; with
+ * none, nothing is decided in the host.
+ */
+export function renderApproval(presentation) {
+    const renderer = RENDERERS.find(one => one.matches(presentation));
+    if (!renderer)
+        return {
+            complete: false,
+            fields: presentation.fields.map(({ label, value }) => ({ label, value })),
+            reasons: [
+                `@Datalayer has no way yet to show ${presentation.tool_name} whole: review it in Datalayer.`,
+            ],
+            renderer: 'none',
+        };
+    return renderer.render(presentation);
+}

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

@@ -0,0 +1,95 @@
+import { type ApprovalPresentation, type HostDelivery } from './contracts';
+/** What ai-agents refused, with its status and its sentence. */
+export declare class HostRefusedError extends Error {
+    readonly status: number;
+    readonly detail: string;
+    readonly what: string;
+    constructor(status: number, detail: string, what: string);
+}
+export type HostSelf = Readonly<{
+    accountUid: string;
+    channels: ReadonlyArray<{
+        deployment: string;
+        id: string;
+        state: 'allow' | 'deny';
+    }>;
+    defaultDeployment?: string;
+    deployments: ReadonlyArray<{
+        appName: string;
+        kept: boolean;
+        uid: string;
+    }>;
+    directOnly: readonly string[];
+    paused: boolean;
+}>;
+export type BoundHost = Readonly<{
+    defaultDeployment?: string;
+    hostKey: string;
+    hostUid: string;
+    name?: string;
+}>;
+/**
+ * The generic host routes of ai-agents (plans/SLACK.md §4.3, plans/DISCORD.md
+ * §4.3) a host calls besides the credential exchange: as the installation,
+ * with its key in `X-Datalayer-Host-Key`, or as a person, with the host token
+ * the exchange answered. Any host speaks them.
+ */
+export declare class DatalayerHostClient {
+    #private;
+    readonly apiUrl: string;
+    readonly fetchImplementation: typeof fetch;
+    constructor(apiUrl: string, fetchImplementation?: typeof fetch);
+    /** Bind the installation its owner set up, with the code their browser carried (§3.1). */
+    bind(input: {
+        code: string;
+        externalId: string;
+        name?: string;
+    }): Promise<BoundHost>;
+    /** The installation was removed from its host: it ends at Datalayer (revocation). */
+    uninstalled(hostKey: string): Promise<void>;
+    /**
+     * The installation as Datalayer keeps it: the deployments it allows (with
+     * their application's name and whether each is kept on), the default, the
+     * channel policy and whether it is paused.
+     */
+    self(hostKey: string): Promise<HostSelf>;
+    /** The host unlinks one of its users: how many links ended. */
+    unlink(hostKey: string, externalUserId: string): Promise<number>;
+    /** A one-use code a host user redeems, signed in to Datalayer, to link their account. */
+    linkCode(hostKey: string, externalUserId: string, externalUserName?: string): Promise<{
+        code: string;
+        expiresIn: number;
+    }>;
+    /** Whether a host user is linked, and to which principal. */
+    linkState(hostKey: string, externalUserId: string): Promise<{
+        linked: boolean;
+        principalUid?: string;
+    }>;
+    /** Where deliveries are pushed: answered the secret they are signed with, once. */
+    setWebhook(hostKey: string, url: string): Promise<{
+        signingSecret: string;
+        version: number;
+    }>;
+    /** What the installation has not acknowledged, oldest first: pushed or not. */
+    outbox(hostKey: string, limit?: number): Promise<HostDelivery[]>;
+    acknowledge(hostKey: string, deliveryUid: string): Promise<void>;
+    /**
+     * *Open in Datalayer* (S-305): a one-use code for the host token's person
+     * that opens one session or approval after sign-in. Answers the landing's
+     * path that redeems it; never a bearer token in a URL.
+     */
+    handoff(token: string, kind: 'session' | 'approval', target: string): Promise<{
+        path: string;
+        expiresIn: number;
+    }>;
+    /** How an approval is shown, read as the person it waits on (their host token). */
+    presentation(token: string, approvalId: string): Promise<ApprovalPresentation>;
+    /** Decide an approval as its person, on the very presentation shown (its digest). */
+    decide(token: string, approvalId: string, decision: {
+        approve: boolean;
+        digest: string;
+        note?: string;
+    }): Promise<{
+        status: string;
+    }>;
+}

package/lib/portable/hosts/client.js

@@ -0,0 +1,174 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * The ai-agents host client every chat host calls (moved from the Slack
+ * service, plans/DISCORD.md DC-004).
+ *
+ * @module portable/hosts/client
+ */
+import { z } from 'zod';
+import { bindSchema, decisionSchema, deliveryOfOutbox, HOST_KEY_HEADER, linkCodeSchema, linkStateSchema, handoffSchema, presentationSchema, selfSchema, webhookSchema, } from './contracts';
+/** What ai-agents refused, with its status and its sentence. */
+export class HostRefusedError extends Error {
+    status;
+    detail;
+    what;
+    constructor(status, detail, what) {
+        super(`${what} (${status}): ${detail}`);
+        this.status = status;
+        this.detail = detail;
+        this.what = what;
+    }
+}
+/**
+ * The generic host routes of ai-agents (plans/SLACK.md §4.3, plans/DISCORD.md
+ * §4.3) a host calls besides the credential exchange: as the installation,
+ * with its key in `X-Datalayer-Host-Key`, or as a person, with the host token
+ * the exchange answered. Any host speaks them.
+ */
+export class DatalayerHostClient {
+    apiUrl;
+    fetchImplementation;
+    constructor(apiUrl, fetchImplementation = fetch) {
+        this.apiUrl = apiUrl;
+        this.fetchImplementation = fetchImplementation;
+    }
+    #url(path) {
+        return `${this.apiUrl}/api/ai-agents/v1${path}`;
+    }
+    async #call(what, path, init, schema) {
+        const headers = {};
+        if (init.body !== undefined)
+            headers['content-type'] = 'application/json';
+        if (init.hostKey)
+            headers[HOST_KEY_HEADER] = init.hostKey;
+        if (init.token)
+            headers.authorization = `Bearer ${init.token}`;
+        const response = await this.fetchImplementation(this.#url(path), {
+            body: init.body === undefined ? undefined : JSON.stringify(init.body),
+            headers,
+            method: init.method ?? 'GET',
+        });
+        const body = (await response.json().catch(() => ({})));
+        if (!response.ok || body.success === false)
+            throw new HostRefusedError(response.status, typeof body.detail === 'string' ? body.detail : 'refused', what);
+        return schema.parse(body);
+    }
+    /** Bind the installation its owner set up, with the code their browser carried (§3.1). */
+    async bind(input) {
+        const bound = await this.#call('Datalayer did not bind the installation', '/apps/hosts/bind', {
+            body: {
+                code: input.code,
+                external_id: input.externalId,
+                name: input.name ?? '',
+            },
+            method: 'POST',
+        }, bindSchema);
+        return {
+            defaultDeployment: bound.host.default_deployment || undefined,
+            hostKey: bound.host_key,
+            hostUid: bound.host.uid,
+            name: bound.host.name,
+        };
+    }
+    /** The installation was removed from its host: it ends at Datalayer (revocation). */
+    async uninstalled(hostKey) {
+        await this.#call('Datalayer did not end the installation', '/apps/hosts/self', { hostKey, method: 'DELETE' }, z.unknown());
+    }
+    /**
+     * The installation as Datalayer keeps it: the deployments it allows (with
+     * their application's name and whether each is kept on), the default, the
+     * channel policy and whether it is paused.
+     */
+    async self(hostKey) {
+        const answered = await this.#call('Datalayer did not answer the installation', '/apps/hosts/self', { hostKey }, selfSchema);
+        const host = answered.host;
+        return {
+            accountUid: host.account_uid ?? '',
+            channels: (host.channels ?? []).map(one => ({
+                deployment: one.deployment ?? '',
+                id: one.id,
+                state: one.state,
+            })),
+            defaultDeployment: host.default_deployment || undefined,
+            deployments: host.deployments.map(one => ({
+                appName: one.app_name ?? '',
+                kept: one.kept ?? false,
+                uid: one.uid,
+            })),
+            directOnly: host.direct_only ?? [],
+            paused: host.paused ?? false,
+        };
+    }
+    /** The host unlinks one of its users: how many links ended. */
+    async unlink(hostKey, externalUserId) {
+        const answered = await this.#call('Datalayer did not unlink the account', `/apps/hosts/self/links/${encodeURIComponent(externalUserId)}`, { hostKey, method: 'DELETE' }, z.object({ revoked: z.number().int() }));
+        return answered.revoked;
+    }
+    /** A one-use code a host user redeems, signed in to Datalayer, to link their account. */
+    async linkCode(hostKey, externalUserId, externalUserName = '') {
+        const answered = await this.#call('Datalayer did not answer a link code', '/apps/hosts/self/link-codes', {
+            body: {
+                external_user_id: externalUserId,
+                external_user_name: externalUserName,
+            },
+            hostKey,
+            method: 'POST',
+        }, linkCodeSchema);
+        return { code: answered.code, expiresIn: answered.expires_in };
+    }
+    /** Whether a host user is linked, and to which principal. */
+    async linkState(hostKey, externalUserId) {
+        const state = await this.#call('Datalayer did not say whether the account is linked', `/apps/hosts/self/links/${encodeURIComponent(externalUserId)}`, { hostKey }, linkStateSchema);
+        return { linked: state.linked, principalUid: state.principal_uid };
+    }
+    /** Where deliveries are pushed: answered the secret they are signed with, once. */
+    async setWebhook(hostKey, url) {
+        const hook = await this.#call('Datalayer did not register the delivery address', '/apps/hosts/self/delivery', {
+            body: {
+                events: ['approval.requested', 'approval.decided', 'turn.completed'],
+                url,
+            },
+            hostKey,
+            method: 'PUT',
+        }, webhookSchema);
+        return { signingSecret: hook.signing_secret, version: hook.version };
+    }
+    /** What the installation has not acknowledged, oldest first: pushed or not. */
+    async outbox(hostKey, limit = 100) {
+        const listed = await this.#call('Datalayer did not answer the outbox', `/apps/hosts/self/deliveries?limit=${limit}`, { hostKey }, z.object({ deliveries: z.array(z.unknown()) }));
+        return listed.deliveries.map(deliveryOfOutbox);
+    }
+    async acknowledge(hostKey, deliveryUid) {
+        await this.#call('Datalayer did not take the acknowledgement', `/apps/hosts/self/deliveries/${encodeURIComponent(deliveryUid)}/ack`, { hostKey, method: 'POST' }, z.unknown());
+    }
+    /**
+     * *Open in Datalayer* (S-305): a one-use code for the host token's person
+     * that opens one session or approval after sign-in. Answers the landing's
+     * path that redeems it; never a bearer token in a URL.
+     */
+    async handoff(token, kind, target) {
+        const made = await this.#call('Datalayer did not make the link', '/apps/hosts/handoffs', { body: { kind, target }, method: 'POST', token }, handoffSchema);
+        return { expiresIn: made.expires_in, path: made.path };
+    }
+    /** How an approval is shown, read as the person it waits on (their host token). */
+    async presentation(token, approvalId) {
+        const answered = await this.#call('Datalayer did not answer the approval', `/tool-approvals/${encodeURIComponent(approvalId)}/presentation`, { token }, z.object({ presentation: presentationSchema }));
+        return answered.presentation;
+    }
+    /** Decide an approval as its person, on the very presentation shown (its digest). */
+    async decide(token, approvalId, decision) {
+        const answered = await this.#call('Datalayer did not take the decision', `/apps/hosts/approvals/${encodeURIComponent(approvalId)}/decision`, {
+            body: {
+                approve: decision.approve,
+                digest: decision.digest,
+                note: decision.note || null,
+            },
+            method: 'POST',
+            token,
+        }, decisionSchema);
+        return { status: answered.approval.status };
+    }
+}

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

@@ -0,0 +1,199 @@
+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 declare const HOST_KEY_HEADER = "X-Datalayer-Host-Key";
+export declare const SIGNATURE_HEADER = "X-Datalayer-Signature";
+export declare const TIMESTAMP_HEADER = "X-Datalayer-Timestamp";
+export declare const DELIVERY_HEADER = "X-Datalayer-Delivery";
+export declare const IDEMPOTENCY_HEADER = "Idempotency-Key";
+/** The presentation version the hosts render; another is reviewed in Datalayer. */
+export declare const PRESENTATION_VERSION = 1;
+export declare const bindSchema: z.ZodObject<{
+    host: z.ZodObject<{
+        uid: z.ZodString;
+        state: z.ZodString;
+        name: z.ZodOptional<z.ZodString>;
+        default_deployment: z.ZodOptional<z.ZodString>;
+    }, z.core.$loose>;
+    host_key: z.ZodString;
+}, z.core.$strip>;
+/** What a link code is redeemed at: the landing's confirm page. */
+export declare 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 declare const selfSchema: z.ZodObject<{
+    host: z.ZodObject<{
+        uid: z.ZodString;
+        account_uid: z.ZodOptional<z.ZodString>;
+        default_deployment: z.ZodOptional<z.ZodString>;
+        deployments: z.ZodArray<z.ZodObject<{
+            uid: z.ZodString;
+            app_name: z.ZodOptional<z.ZodString>;
+            kept: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$loose>>;
+        channels: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            state: z.ZodEnum<{
+                allow: "allow";
+                deny: "deny";
+            }>;
+            deployment: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>>;
+        direct_only: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        paused: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$loose>;
+}, z.core.$strip>;
+/** `POST /apps/hosts/handoffs`: a one-use code that opens one session or approval (S-305). */
+export declare const handoffSchema: z.ZodObject<{
+    code: z.ZodString;
+    expires_in: z.ZodNumber;
+    path: z.ZodString;
+}, z.core.$strip>;
+export declare const linkStateSchema: z.ZodObject<{
+    linked: z.ZodBoolean;
+    principal_uid: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const webhookSchema: z.ZodObject<{
+    url: z.ZodURL;
+    events: z.ZodArray<z.ZodString>;
+    version: z.ZodNumber;
+    signing_secret: z.ZodString;
+}, z.core.$strip>;
+/** One delivery of the outbox, as `GET …/self/deliveries` lists it. */
+export declare const outboxItemSchema: z.ZodObject<{
+    uid: z.ZodString;
+    event: z.ZodString;
+    payload: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    state: z.ZodString;
+}, z.core.$loose>;
+export declare const decisionSchema: z.ZodObject<{
+    approval: z.ZodObject<{
+        id: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        status: z.ZodString;
+    }, z.core.$loose>;
+}, z.core.$strip>;
+export declare const linkCodeSchema: z.ZodObject<{
+    code: z.ZodString;
+    expires_in: z.ZodNumber;
+    confirm: z.ZodString;
+}, z.core.$strip>;
+export declare const exchangeSchema: z.ZodObject<{
+    access_token: z.ZodString;
+    token_type: z.ZodLiteral<"Bearer">;
+    expires_in: z.ZodNumber;
+    exp: z.ZodNumber;
+    principal_uid: z.ZodString;
+    host_uid: z.ZodString;
+    deployment: z.ZodObject<{
+        uid: z.ZodString;
+        app_uid: z.ZodString;
+        app_name: z.ZodString;
+        version: z.ZodNumber;
+    }, z.core.$strip>;
+    session_api: z.ZodObject<{
+        url: z.ZodURL;
+        agent: z.ZodString;
+    }, z.core.$strip>;
+    user_token: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type HostExchange = z.infer<typeof exchangeSchema>;
+export declare const presentationSchema: z.ZodObject<{
+    version: z.ZodNumber;
+    approval_id: z.ZodString;
+    status: z.ZodString;
+    owner_uid: z.ZodString;
+    tool_name: z.ZodString;
+    action_class: z.ZodEnum<{
+        unknown: "unknown";
+        read: "read";
+        write: "write";
+        send: "send";
+        delete: "delete";
+        publish: "publish";
+        execute: "execute";
+        financial: "financial";
+    }>;
+    session_uid: z.ZodString;
+    created_at: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    expires_at: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    fields: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        label: z.ZodString;
+        value: z.ZodString;
+    }, z.core.$strip>>;
+    arguments: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    secret_fields: z.ZodArray<z.ZodString>;
+    complete: z.ZodBoolean;
+    host_may_decide: z.ZodBoolean;
+    reasons: z.ZodArray<z.ZodString>;
+    digest: z.ZodString;
+}, z.core.$strip>;
+export type ApprovalPresentation = z.infer<typeof presentationSchema>;
+export declare const deliverySchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    delivery: z.ZodString;
+    event: z.ZodLiteral<"approval.requested">;
+    payload: z.ZodObject<{
+        approval_id: z.ZodString;
+        tool_name: z.ZodString;
+        presentation: z.ZodString;
+        session_uid: z.ZodString;
+        deployment_uid: z.ZodString;
+        target: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    }, z.core.$loose>;
+}, z.core.$strip>, z.ZodObject<{
+    delivery: z.ZodString;
+    event: z.ZodLiteral<"approval.decided">;
+    payload: z.ZodObject<{
+        approval_id: z.ZodString;
+        status: z.ZodString;
+        decided_by: z.ZodString;
+        session_uid: z.ZodString;
+        deployment_uid: z.ZodString;
+        target: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    }, z.core.$loose>;
+}, z.core.$strip>, z.ZodObject<{
+    delivery: z.ZodString;
+    event: z.ZodLiteral<"turn.completed">;
+    payload: z.ZodObject<{
+        record_entry: z.ZodString;
+        session_uid: z.ZodString;
+        deployment_uid: z.ZodString;
+        target: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    }, z.core.$loose>;
+}, z.core.$strip>], "event">;
+export type HostDelivery = z.infer<typeof deliverySchema>;
+/** An outbox item read as the delivery a push would have carried. */
+export declare function deliveryOfOutbox(item: unknown): HostDelivery;
+/**
+ * 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 declare function hostMayDecide(presentation: ApprovalPresentation): boolean;
+/** `v1=` HMAC-SHA256 of `"<timestamp>.<raw body>"`, as ai-agents signs a push. */
+export declare function deliverySignature(secret: string, timestamp: number, rawBody: string | Buffer): string;
+/**
+ * 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 declare function verifyDelivery(input: {
+    nowSeconds?: number;
+    rawBody: string | Buffer;
+    secret: string;
+    signature: string | undefined;
+    timestamp: string | undefined;
+    toleranceSeconds?: number;
+}): HostDelivery;