@datalayer/agent-runtimes 1.5.44 → 1.5.46

package/lib/portable/hosts/agentClient.js

@@ -0,0 +1,346 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * A chat host's turns on Datalayer: the host credential exchange, a turn
+ * started or sent on the deployment's session API (idempotent by the host's
+ * event id), its AG-UI stream reduced to semantic events, and its session
+ * mapped to the host's thread so approvals and completions are delivered
+ * (SLACK §4.3, DISCORD §4.3). What is the host's own (its thread key, the
+ * session uid, the place, the delivery target, its words) is injected as a
+ * `HostShape`. Moved from the Slack service (plans/DISCORD.md DC-004).
+ *
+ * @module portable/hosts/agentClient
+ */
+import { z } from 'zod';
+import { AgUiFrames } from '../agui';
+import { semanticOf, turnOf } from '../semanticOfAgUi';
+import { HostRefusedError } from './client';
+import { exchangeSchema, HOST_KEY_HEADER, IDEMPOTENCY_HEADER, } from './contracts';
+/**
+ * The host credential exchange (SLACK §4.3, 1): the installation's key and
+ * the host user it speaks for, exchanged at ai-agents for a fifteen-minute
+ * host token of the linked person and one deployment.
+ */
+export class HostKeyCredentials {
+    apiUrl;
+    hostKeyFor;
+    shape;
+    fetchImplementation;
+    constructor(apiUrl, hostKeyFor, shape, fetchImplementation = fetch) {
+        this.apiUrl = apiUrl;
+        this.hostKeyFor = hostKeyFor;
+        this.shape = shape;
+        this.fetchImplementation = fetchImplementation;
+    }
+    async exchange(request) {
+        const hostKey = await this.hostKeyFor(request);
+        if (!hostKey) {
+            throw new Error(this.shape.notBound);
+        }
+        return this.exchangeFor({
+            deploymentUid: request.applicationId,
+            externalUserId: request.externalUserId,
+            hostKey,
+            place: this.shape.placeOf(request),
+        });
+    }
+    /** The exchange for one host user and deployment, with a key in hand (a delivery, an action). */
+    async exchangeFor(input) {
+        const response = await this.fetchImplementation(`${this.apiUrl}/api/ai-agents/v1/apps/hosts/self/token`, {
+            body: JSON.stringify({
+                deployment_uid: input.deploymentUid,
+                external_user_id: input.externalUserId,
+                ...(input.place ? { place: input.place } : {}),
+            }),
+            headers: {
+                'content-type': 'application/json',
+                [HOST_KEY_HEADER]: input.hostKey,
+            },
+            method: 'POST',
+        });
+        if (!response.ok) {
+            const body = (await response.json().catch(() => ({})));
+            throw new HostRefusedError(response.status, typeof body.detail === 'string' ? body.detail : 'refused', 'Datalayer refused the host credential exchange');
+        }
+        return exchangeSchema.parse(await response.json());
+    }
+    async forTurn(request) {
+        return hostSessionOf(await this.exchange(request));
+    }
+}
+export function hostSessionOf(exchanged) {
+    return {
+        accessToken: exchanged.access_token,
+        agent: exchanged.session_api.agent,
+        bindable: true,
+        deploymentUid: exchanged.deployment.uid,
+        sessionApiUrl: exchanged.session_api.url,
+        userToken: exchanged.user_token,
+    };
+}
+/**
+ * A turn's credentials: the exchange when its installation holds a host
+ * key; otherwise, in development only, the developer's own (`fallback`);
+ * otherwise a refusal saying the installation is not connected.
+ */
+export class InstallationCredentials {
+    keyed;
+    fallback;
+    constructor(keyed, fallback) {
+        this.keyed = keyed;
+        this.fallback = fallback;
+    }
+    async forTurn(request) {
+        if (await this.keyed.hostKeyFor(request)) {
+            return this.keyed.forTurn(request);
+        }
+        if (this.fallback) {
+            return this.fallback.forTurn(request);
+        }
+        throw new Error(this.keyed.shape.notBound);
+    }
+}
+/**
+ * Development only: the developer's own Datalayer key, and their own kept
+ * deployment, read from ai-agents as its owner. Never in production.
+ */
+export class DevelopmentCredentials {
+    apiUrl;
+    token;
+    fetchImplementation;
+    constructor(apiUrl, token, fetchImplementation = fetch) {
+        this.apiUrl = apiUrl;
+        this.token = token;
+        this.fetchImplementation = fetchImplementation;
+    }
+    async forTurn(request) {
+        const response = await this.fetchImplementation(`${this.apiUrl}/api/ai-agents/v1/apps/deployments/${encodeURIComponent(request.applicationId)}`, { headers: { authorization: `Bearer ${this.token}` } });
+        if (!response.ok) {
+            throw new Error(`Datalayer did not answer the deployment (${response.status}).`);
+        }
+        const body = (await response.json());
+        const kept = body.deployment?.kept;
+        if (!kept?.url || !kept.agent_id) {
+            throw new Error('The deployment is not kept always on: turn it on under Ship.');
+        }
+        return {
+            accessToken: this.token,
+            agent: kept.agent_id,
+            bindable: false,
+            deploymentUid: request.applicationId,
+            sessionApiUrl: `${kept.url.replace(/\/+$/, '')}/api/v1/apps/sessions`,
+        };
+    }
+}
+/** What `GET /api/v1/apps/current` answers that a host reads: the application's starters. */
+const currentAppSchema = z.object({
+    starters: z.array(z.object({ label: z.string(), message: z.string() })),
+});
+/**
+ * An application's starters (SLACK S-104), read from its runtime as the
+ * linked person: the host credential exchange (no place: what is suggested
+ * is private to them), then `GET /api/v1/apps/current` beside the session
+ * API it answers. A runtime that does not answer starters is refused.
+ */
+export class HostStarters {
+    apiUrl;
+    keyed;
+    hostKeyOf;
+    fetchImplementation;
+    constructor(apiUrl, keyed, hostKeyOf, fetchImplementation = fetch) {
+        this.apiUrl = apiUrl;
+        this.keyed = keyed;
+        this.hostKeyOf = hostKeyOf;
+        this.fetchImplementation = fetchImplementation;
+    }
+    async startersOf(key, externalUserId, applicationId) {
+        const hostKey = await this.hostKeyOf(key);
+        if (!hostKey) {
+            throw new Error(this.keyed.shape.notBound);
+        }
+        const exchanged = await this.keyed.exchangeFor({
+            deploymentUid: applicationId,
+            externalUserId,
+            hostKey,
+        });
+        const sessions = exchanged.session_api.url.replace(/\/+$/, '');
+        assertTrustedStreamUrl(this.apiUrl, sessions);
+        if (!sessions.endsWith('/api/v1/apps/sessions')) {
+            throw new Error("Datalayer answered a session API that is not an application runtime's.");
+        }
+        const response = await this.fetchImplementation(`${sessions.slice(0, -'/sessions'.length)}/current`, { headers: { authorization: `Bearer ${exchanged.access_token}` } });
+        if (!response.ok) {
+            throw new HostRefusedError(response.status, 'refused', 'The application did not say what it suggests asking');
+        }
+        return currentAppSchema.parse(await response.json()).starters;
+    }
+}
+/** Each AG-UI event of a run's `text/event-stream` body, as it arrives (`AgUiFrames`). */
+export async function* agUiEventsOf(body) {
+    const decoder = new TextDecoder();
+    const frames = new AgUiFrames();
+    const reader = body.getReader();
+    try {
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done) {
+                break;
+            }
+            yield* frames.push(decoder.decode(value, { stream: true }));
+        }
+        yield* frames.push(decoder.decode());
+        yield* frames.end();
+    }
+    finally {
+        reader.releaseLock();
+    }
+}
+/**
+ * The host's Datalayer client: a turn is started or sent on the deployment's
+ * session API (idempotent by the host's event id, SLACK §4.3, 2), its AG-UI
+ * stream reduced to semantic events, and its session mapped to the host's
+ * thread so that approvals and completions are delivered (§4.3, 3).
+ */
+export class HttpAgentClient {
+    apiUrl;
+    credentials;
+    shape;
+    fetchImplementation;
+    hostKeyFor;
+    constructor(apiUrl, credentials, shape, fetchImplementation = fetch, hostKeyFor) {
+        this.apiUrl = apiUrl;
+        this.credentials = credentials;
+        this.shape = shape;
+        this.fetchImplementation = fetchImplementation;
+        this.hostKeyFor = hostKeyFor;
+    }
+    async startTurn(request) {
+        const host = await this.credentials.forTurn(request);
+        assertTrustedStreamUrl(this.apiUrl, host.sessionApiUrl);
+        const sessionId = request.sessionId ?? this.shape.sessionUidOf(request);
+        const headers = {
+            accept: 'text/event-stream',
+            authorization: `Bearer ${host.accessToken}`,
+            'content-type': 'application/json',
+            [IDEMPOTENCY_HEADER]: request.externalEventId,
+        };
+        const response = request.sessionId
+            ? await this.fetchImplementation(`${host.sessionApiUrl}/${encodeURIComponent(sessionId)}/messages`, {
+                body: JSON.stringify({
+                    external_event_id: request.externalEventId,
+                    text: request.prompt,
+                }),
+                headers,
+                method: 'POST',
+            })
+            : await this.fetchImplementation(host.sessionApiUrl, {
+                body: JSON.stringify({
+                    agent: host.agent,
+                    deployment_uid: host.deploymentUid,
+                    external_event_id: request.externalEventId,
+                    opener: request.prompt,
+                    session: sessionId,
+                    ...(host.userToken ? { user_token: host.userToken } : {}),
+                }),
+                headers,
+                method: 'POST',
+            });
+        if (!response.ok || !response.body) {
+            throw new Error(`Datalayer refused the turn (${response.status}).`);
+        }
+        const hostKey = host.bindable && this.hostKeyFor
+            ? await this.hostKeyFor(request)
+            : undefined;
+        if (hostKey) {
+            await this.#bind(request, host, sessionId, hostKey);
+        }
+        const run = {};
+        return {
+            run,
+            sessionId,
+            updates: this.#updates(response.body, host, sessionId, run),
+        };
+    }
+    async stopTurn(sessionId, request) {
+        const host = await this.credentials.forTurn(request);
+        assertTrustedStreamUrl(this.apiUrl, host.sessionApiUrl);
+        const response = await this.fetchImplementation(`${host.sessionApiUrl}/${encodeURIComponent(sessionId)}/stop`, {
+            headers: { authorization: `Bearer ${host.accessToken}` },
+            method: 'POST',
+        });
+        if (!response.ok && response.status !== 409) {
+            throw new Error(`Datalayer could not stop the turn (${response.status}).`);
+        }
+    }
+    async #bind(request, host, sessionId, hostKey) {
+        const response = await this.fetchImplementation(`${this.apiUrl}/api/ai-agents/v1/apps/hosts/sessions/${encodeURIComponent(sessionId)}`, {
+            // Handed back with every delivery: the thread, and the host user the
+            // host token speaks for, whom an approval waits on.
+            body: JSON.stringify({ target: this.shape.targetOf(request) }),
+            headers: {
+                authorization: `Bearer ${host.accessToken}`,
+                'content-type': 'application/json',
+                [HOST_KEY_HEADER]: hostKey,
+            },
+            method: 'PUT',
+        });
+        if (!response.ok) {
+            throw new Error(`Datalayer did not map the thread to its session (${response.status}).`);
+        }
+    }
+    async *#updates(body, host, sessionId, run) {
+        const tools = new Map();
+        for await (const event of agUiEventsOf(body)) {
+            const turn = turnOf(event);
+            if (turn?.turn) {
+                run.id = turn.turn;
+            }
+            if (turn?.replayed) {
+                // A retry: nothing ran again; what the turn said is the session's.
+                yield* this.#replayed(host, sessionId, turn.state);
+                return;
+            }
+            yield* semanticOf(event, tools);
+        }
+    }
+    async *#replayed(host, sessionId, state) {
+        if (state === 'running') {
+            yield { kind: 'progress', label: 'Still working on this message…' };
+            return;
+        }
+        const text = await lastAnswer(this.fetchImplementation, host, sessionId);
+        if (text === null) {
+            yield {
+                kind: 'error',
+                message: 'This message was already answered in Datalayer.',
+            };
+            return;
+        }
+        yield { kind: 'completion', text };
+    }
+}
+/**
+ * The session's last answer, read with the host token (what a replayed turn
+ * and a `turn.completed` delivery show); `null` when the session is not read.
+ */
+export async function lastAnswer(fetchImplementation, host, sessionId) {
+    const response = await fetchImplementation(`${host.sessionApiUrl}/${encodeURIComponent(sessionId)}/messages`, { headers: { authorization: `Bearer ${host.accessToken}` } });
+    if (!response.ok) {
+        return null;
+    }
+    const { messages } = (await response.json());
+    const last = [...(messages ?? [])]
+        .reverse()
+        .find(message => message.role === 'assistant');
+    return typeof last?.content === 'string' ? last.content : undefined;
+}
+/** A session API or stream URL Datalayer answered: HTTPS, on Datalayer's own origin. */
+export function assertTrustedStreamUrl(baseUrl, streamUrl) {
+    const base = new URL(baseUrl);
+    const stream = new URL(streamUrl);
+    if (stream.protocol !== 'https:' || stream.origin !== base.origin) {
+        throw new Error('Datalayer returned an untrusted stream URL.');
+    }
+}

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

@@ -0,0 +1,43 @@
+import type { ApprovalPresentation } from './contracts';
+/**
+ * Typed approval renderers (plans/SLACK.md §2 rule 6, S-302; plans/DISCORD.md
+ * §3.6). A host offers Approve and Reject only when a renderer that knows the
+ * tool proves that every material argument is shown: each argument the server
+ * presented is named by the renderer, or the card fails closed. An unknown
+ * tool, an argument the renderer does not know, an attachment, and every
+ * destructive, financial or publishing action are reviewed in Datalayer
+ * (SLACK §15, 5). They render ai-agents' presentation v1, a different input
+ * from `../approvals.ts` and `../approvalCard.ts`. Moved from the Slack
+ * service (plans/DISCORD.md DC-004).
+ *
+ * @module portable/hosts/approvalRenderers
+ */
+export type RenderedField = Readonly<{
+    label: string;
+    value: string;
+}>;
+export type RenderedAction = Readonly<{
+    /** The renderer that knew the tool. */
+    renderer: string;
+    /** The fields shown, in order, each whole. */
+    fields: readonly RenderedField[];
+    /** Whether every argument is shown and nothing needs Datalayer. */
+    complete: boolean;
+    /** Why not, in words, when it is not. */
+    reasons: readonly string[];
+}>;
+type Renderer = Readonly<{
+    name: string;
+    matches(presentation: ApprovalPresentation): boolean;
+    render(presentation: ApprovalPresentation): RenderedAction;
+}>;
+/** Action classes that are decided in Datalayer only (§15, 5). */
+export declare const DATALAYER_ONLY: Set<"unknown" | "read" | "write" | "send" | "delete" | "publish" | "execute" | "financial">;
+/** The renderers, the first that matches wins: Datalayer-only before any other. */
+export declare const RENDERERS: readonly Renderer[];
+/**
+ * How a host shows an approval, by the renderer that knows its tool; with
+ * none, nothing is decided in the host.
+ */
+export declare function renderApproval(presentation: ApprovalPresentation): RenderedAction;
+export {};

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