@datalayer/agent-runtimes 1.5.24 → 1.5.25

package/lib/portable/displays.d.ts

@@ -0,0 +1,109 @@
+/**
+ * The protocol displays a run's tool results carry, read strictly for any
+ * renderer (MOBILE M-037, REACTOR_UI RU-1): the page's half of a tool result
+ * — `_meta["reactor.ui/display"]`, as the runtime's AG-UI stream sends it
+ * beside the model's view — decoded into what a card draws.
+ *
+ * - **Sign in at a company** (`…pap.sign-in+json`, and a plain `pap_sign_in`
+ *   or a business's `pact_sign_in` answer): Direct, Device or Mediated, its
+ *   page (`https` only), its code, until when, what it needs.
+ * - **An operation to confirm** (`…pap.confirm+json`): the company's words
+ *   verbatim, its terms, the revision and the one it replaced, what it does
+ *   (a Rules class; `buy` when money moves — a purchase), whether only the
+ *   person may decide. It is answered where approvals are, never here: the
+ *   approval it stands for is named (`approvalId`).
+ * - **What a confirmed operation came to** (`…pap.outcome+json`).
+ * - **What a company answered** (`…pap.replies+json`): each reply with who
+ *   wrote it there (its agent or one of its people), who answers now and
+ *   where the conversation stands — participation.
+ * - **A handoff** (`pap_handoff`'s answer): handed to the company's people,
+ *   or why not.
+ *
+ * Anything else — an unknown type, a known one whose data does not read — is
+ * `unknown`: its type, version and model-safe text, nothing drawn from its
+ * data (diagnosable and safe). Typed decoding fails closed.
+ *
+ * @module portable/displays
+ */
+import { type PapSignInWaiting } from './signIn';
+export declare const PAP_SIGN_IN_TYPE = "application/vnd.datalayer.pap.sign-in+json";
+export declare const PAP_CONFIRM_TYPE = "application/vnd.datalayer.pap.confirm+json";
+export declare const PAP_OUTCOME_TYPE = "application/vnd.datalayer.pap.outcome+json";
+export declare const PAP_REPLIES_TYPE = "application/vnd.datalayer.pap.replies+json";
+/** Where a tool result carries its display for the page. */
+export declare const DISPLAY_META_KEY = "reactor.ui/display";
+/** What confirming an operation does, as an application's Rules class it. */
+export type ActionClass = 'read' | 'write' | 'send' | 'buy' | 'delete' | 'publish';
+export type ProtocolDisplay = ({
+    kind: 'sign-in';
+    id: string;
+} & PapSignInWaiting) | {
+    kind: 'sign-in-refused';
+    id: string;
+    why: string;
+} | {
+    kind: 'confirm';
+    id: string;
+    /** The approval it stands for: answered where approvals are. */
+    approvalId: string;
+    company: string;
+    summary: string;
+    terms: Record<string, unknown>;
+    operationRef: string;
+    revision: number;
+    does: ActionClass | null;
+    signedIn: boolean | null;
+    expiresAt: string;
+    was: {
+        revision: number;
+        terms: Record<string, unknown>;
+    } | null;
+    onlyThePerson: boolean;
+} | {
+    kind: 'outcome';
+    id: string;
+    company: string;
+    summary: string;
+    operationRef: string;
+    revision: number;
+    state: 'in_progress' | 'succeeded' | 'failed' | 'cancelled' | 'expired';
+    result: string;
+    approvedBy: 'user' | 'standing_permission' | null;
+} | {
+    kind: 'replies';
+    id: string;
+    company: string;
+    conversation: string;
+    replies: {
+        sender: 'agent' | 'human';
+        text: string;
+    }[];
+    status: 'working' | 'idle' | 'queued' | 'closed' | null;
+    responder: 'agent' | 'human' | null;
+} | {
+    kind: 'handoff';
+    id: string;
+    handed: boolean;
+    responder: 'agent' | 'human' | null;
+    note: string;
+} | {
+    kind: 'unknown';
+    id: string;
+    type: string;
+    version: number;
+    text: string;
+};
+/** A display's wire (`{type, version, id, text, data}`) decoded, or `unknown` with its text. */
+export declare function protocolDisplayOf(wire: unknown): ProtocolDisplay | null;
+/** `pap_handoff`, as the gateway names it with or without a prefix. */
+export declare const PAP_HANDOFF_TOOL: RegExp;
+/**
+ * The protocol display of a tool's result, or `null` for one that has none:
+ * its embedded display first; else a plain `pap_sign_in`/`pact_sign_in`
+ * answer or a `pap_handoff` answer, read by the tool's name.
+ */
+export declare function displayOfToolResult(toolName: string, result: unknown, id?: string): ProtocolDisplay | null;
+/** What each display says in one line, for a screen reader and a collapsed row. */
+export declare function displayLine(display: ProtocolDisplay): string;
+/** Who wrote a reply, said apart from the person's words and the agent's summaries (PAP-7.8-01). */
+export declare const replyAuthor: (company: string, sender: "agent" | "human") => string;

package/lib/portable/displays.js

@@ -0,0 +1,261 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * The protocol displays a run's tool results carry, read strictly for any
+ * renderer (MOBILE M-037, REACTOR_UI RU-1): the page's half of a tool result
+ * — `_meta["reactor.ui/display"]`, as the runtime's AG-UI stream sends it
+ * beside the model's view — decoded into what a card draws.
+ *
+ * - **Sign in at a company** (`…pap.sign-in+json`, and a plain `pap_sign_in`
+ *   or a business's `pact_sign_in` answer): Direct, Device or Mediated, its
+ *   page (`https` only), its code, until when, what it needs.
+ * - **An operation to confirm** (`…pap.confirm+json`): the company's words
+ *   verbatim, its terms, the revision and the one it replaced, what it does
+ *   (a Rules class; `buy` when money moves — a purchase), whether only the
+ *   person may decide. It is answered where approvals are, never here: the
+ *   approval it stands for is named (`approvalId`).
+ * - **What a confirmed operation came to** (`…pap.outcome+json`).
+ * - **What a company answered** (`…pap.replies+json`): each reply with who
+ *   wrote it there (its agent or one of its people), who answers now and
+ *   where the conversation stands — participation.
+ * - **A handoff** (`pap_handoff`'s answer): handed to the company's people,
+ *   or why not.
+ *
+ * Anything else — an unknown type, a known one whose data does not read — is
+ * `unknown`: its type, version and model-safe text, nothing drawn from its
+ * data (diagnosable and safe). Typed decoding fails closed.
+ *
+ * @module portable/displays
+ */
+import { isPapSignInTool, readPapSignIn, } from './signIn';
+export const PAP_SIGN_IN_TYPE = 'application/vnd.datalayer.pap.sign-in+json';
+export const PAP_CONFIRM_TYPE = 'application/vnd.datalayer.pap.confirm+json';
+export const PAP_OUTCOME_TYPE = 'application/vnd.datalayer.pap.outcome+json';
+export const PAP_REPLIES_TYPE = 'application/vnd.datalayer.pap.replies+json';
+/** Where a tool result carries its display for the page. */
+export const DISPLAY_META_KEY = 'reactor.ui/display';
+const record = (value) => value && typeof value === 'object' && !Array.isArray(value)
+    ? value
+    : null;
+const text = (value) => typeof value === 'string' ? value : '';
+const words = (value) => text(value).trim();
+const count = (value) => typeof value === 'number' && Number.isInteger(value) && value >= 1
+    ? value
+    : 0;
+const ACTIONS = [
+    'read',
+    'write',
+    'send',
+    'buy',
+    'delete',
+    'publish',
+];
+const OUTCOMES = [
+    'in_progress',
+    'succeeded',
+    'failed',
+    'cancelled',
+    'expired',
+];
+const STATUSES = ['working', 'idle', 'queued', 'closed'];
+const who = (value) => value === 'agent' || value === 'human' ? value : null;
+/** A display's wire (`{type, version, id, text, data}`) decoded, or `unknown` with its text. */
+export function protocolDisplayOf(wire) {
+    const shown = record(wire);
+    if (!shown || !text(shown.type)) {
+        return null;
+    }
+    const id = text(shown.id);
+    const data = record(shown.data) ?? {};
+    const unknown = {
+        kind: 'unknown',
+        id,
+        type: text(shown.type),
+        version: typeof shown.version === 'number' ? shown.version : 0,
+        text: text(shown.text),
+    };
+    switch (shown.type) {
+        case PAP_SIGN_IN_TYPE: {
+            const read = readPapSignIn({ status: 'waiting_for_the_person', ...data });
+            if (!read)
+                return unknown;
+            return 'refused' in read
+                ? { kind: 'sign-in-refused', id, why: read.refused }
+                : { kind: 'sign-in', id, ...read };
+        }
+        case PAP_CONFIRM_TYPE: {
+            const company = words(data.company);
+            const summary = text(data.summary);
+            const operationRef = words(data.operation_ref);
+            const revision = count(data.revision);
+            const terms = record(data.terms);
+            const was = record(data.was);
+            const wasRevision = was ? count(was.revision) : 0;
+            if (!company ||
+                !summary.trim() ||
+                !operationRef ||
+                !revision ||
+                !terms ||
+                !id.endsWith('-confirm')) {
+                return unknown;
+            }
+            if (was && (!wasRevision || wasRevision >= revision)) {
+                return unknown;
+            }
+            const does = data.does === null || data.does === undefined
+                ? null
+                : ACTIONS.find(a => a === data.does);
+            if (does === undefined)
+                return unknown;
+            const session = record(data.session);
+            return {
+                kind: 'confirm',
+                id,
+                approvalId: id.slice(0, -'-confirm'.length),
+                company,
+                summary,
+                terms,
+                operationRef,
+                revision,
+                does,
+                signedIn: session && typeof session.signed_in === 'boolean'
+                    ? session.signed_in
+                    : null,
+                expiresAt: text(data.expires_at),
+                was: was
+                    ? { revision: wasRevision, terms: record(was.terms) ?? {} }
+                    : null,
+                onlyThePerson: data.only_the_person === true,
+            };
+        }
+        case PAP_OUTCOME_TYPE: {
+            const state = OUTCOMES.find(s => s === data.state);
+            const company = words(data.company);
+            const summary = text(data.summary);
+            const result = text(data.result);
+            if (!state ||
+                !company ||
+                !summary.trim() ||
+                !words(data.operation_ref) ||
+                !count(data.revision)) {
+                return unknown;
+            }
+            // Final, it says what it came to in the company's words; in progress, nothing yet.
+            if ((state === 'in_progress') !== !result.trim())
+                return unknown;
+            return {
+                kind: 'outcome',
+                id,
+                company,
+                summary,
+                operationRef: words(data.operation_ref),
+                revision: count(data.revision),
+                state,
+                result,
+                approvedBy: data.approved_by === 'user' ||
+                    data.approved_by === 'standing_permission'
+                    ? data.approved_by
+                    : null,
+            };
+        }
+        case PAP_REPLIES_TYPE: {
+            const company = words(data.company);
+            const conversation = text(data.conversation);
+            const replies = Array.isArray(data.replies)
+                ? data.replies.map(record).map(reply => ({
+                    sender: who(reply?.sender),
+                    text: text(reply?.text),
+                }))
+                : [];
+            if (!company ||
+                !/^[A-Za-z0-9_-]{1,256}$/.test(conversation) ||
+                !replies.length ||
+                replies.some(reply => !reply.sender || !reply.text.trim())) {
+                return unknown;
+            }
+            return {
+                kind: 'replies',
+                id,
+                company,
+                conversation,
+                replies: replies,
+                status: STATUSES.find(s => s === data.status) ?? null,
+                responder: who(data.responder),
+            };
+        }
+        default:
+            return unknown;
+    }
+}
+/** `pap_handoff`, as the gateway names it with or without a prefix. */
+export const PAP_HANDOFF_TOOL = /(^|[_.:\-/])pap_handoff$/;
+/**
+ * The protocol display of a tool's result, or `null` for one that has none:
+ * its embedded display first; else a plain `pap_sign_in`/`pact_sign_in`
+ * answer or a `pap_handoff` answer, read by the tool's name.
+ */
+export function displayOfToolResult(toolName, result, id = '') {
+    const answer = record(result);
+    const embedded = record(answer?._meta)?.[DISPLAY_META_KEY];
+    if (embedded !== undefined) {
+        return protocolDisplayOf(embedded);
+    }
+    if (isPapSignInTool(toolName)) {
+        const read = readPapSignIn(result);
+        if (!read)
+            return null;
+        return 'refused' in read
+            ? { kind: 'sign-in-refused', id, why: read.refused }
+            : { kind: 'sign-in', id, ...read };
+    }
+    if (PAP_HANDOFF_TOOL.test(toolName) && answer) {
+        const status = text(answer.status);
+        if (!status)
+            return null;
+        return {
+            kind: 'handoff',
+            id,
+            handed: status !== 'closed' && status !== 'direct_conversation_open',
+            responder: who(answer.responder),
+            note: text(answer.note),
+        };
+    }
+    return null;
+}
+/** What each display says in one line, for a screen reader and a collapsed row. */
+export function displayLine(display) {
+    switch (display.kind) {
+        case 'sign-in':
+            return display.mode === 'mediated'
+                ? `Sign in through ${display.host}`
+                : `Sign in at ${display.company || display.host}`;
+        case 'sign-in-refused':
+            return display.why;
+        case 'confirm':
+            return `${display.company} asks you to confirm: ${display.summary} (version ${display.revision})`;
+        case 'outcome':
+            return display.state === 'in_progress'
+                ? `Still in progress at ${display.company}: ${display.summary}`
+                : `${OUTCOME_LEADS[display.state]} ${display.company}: ${display.result}`;
+        case 'replies':
+            return `${display.company} answered${display.responder === 'human' ? ': one of its people is answering' : ''}`;
+        case 'handoff':
+            return display.handed
+                ? `Handed to ${display.responder === 'human' ? 'one of the company’s people' : 'the company'}`
+                : display.note || 'Nothing was handed over.';
+        case 'unknown':
+            return display.text || `A display this app cannot draw (${display.type})`;
+    }
+}
+const OUTCOME_LEADS = {
+    succeeded: 'Done at',
+    failed: 'Failed at',
+    cancelled: 'Cancelled at',
+    expired: 'Expired at',
+};
+/** Who wrote a reply, said apart from the person's words and the agent's summaries (PAP-7.8-01). */
+export const replyAuthor = (company, sender) => sender === 'human'
+    ? `${company}, one of its people`
+    : `${company}, its agent`;

package/lib/portable/fixtures.js

@@ -32,6 +32,7 @@ export function conversationFixture() {
                 status: 'complete',
                 result: 'Shipped on Monday.',
                 error: '',
+                display: null,
             },
             {
                 kind: 'tool',
@@ -41,6 +42,7 @@ export function conversationFixture() {
                 status: 'error',
                 result: '',
                 error: 'Refused by its rule.',
+                display: null,
             },
             {
                 kind: 'step',

package/lib/portable/index.d.ts

@@ -13,7 +13,10 @@ export { ASKED_FOR_TAG, askedOf, RUN_END_WORDS } from './records';
 export { messagesOfThread, openThread, snapshotOfStream, THREAD_WORDS, } from './thread';
 export { CUT_MARK, DIAGNOSTIC_LIMIT, emptyConversation, formFieldsOf, ITEM_LIMIT, MESSAGE_TEXT_LIMIT, questionOf, questionWords, reduceConversation, TOOL_TEXT_LIMIT, withError, withPrompt, withTurnEnded, type ConversationItem, type ConversationQuestion, type ConversationState, type TurnEnd, } from './conversation';
 export { PRESENCE_LINES, presenceOfConversation, presenceState, presenceToolOf, type PresenceState, type PresenceTool, } from './presence';
-export { ANSWER_BELOW, ANSWER_COMPLETE, composerOf, droppedWords, ENDED_WORDS, messageLabel, OPENING_WORDS, presenceLine, showsQuestion, stepLine, TOOL_STATUS_WORDS, toolLabel, type ComposerProps, type ComposerState, type ConversationViewProps, type ErrorItem, type ErrorRowProps, type MessageItem, type MessageRowProps, type PresenceLineProps, type QuestionCardProps, type StepItem, type StepRowProps, type ToolItem, type ToolRowProps, type TurnEndItem, type TurnEndRowProps, } from './views';
+export { ANSWER_BELOW, ANSWER_COMPLETE, composerOf, droppedWords, ENDED_WORDS, messageLabel, OPENING_WORDS, presenceLine, showsQuestion, stepLine, TOOL_STATUS_WORDS, toolLabel, type ComposerProps, type ComposerState, type ConversationViewProps, type ErrorItem, type ErrorRowProps, type MessageItem, type MessageRowProps, type PresenceLineProps, type ProtocolDisplayProps, type QuestionCardProps, type StepItem, type StepRowProps, type ToolItem, type ToolRowProps, type TurnEndItem, type TurnEndRowProps, } from './views';
 export { conversationFixture } from './fixtures';
+export { DISPLAY_META_KEY, displayLine, displayOfToolResult, PAP_CONFIRM_TYPE, PAP_HANDOFF_TOOL, PAP_OUTCOME_TYPE, PAP_REPLIES_TYPE, PAP_SIGN_IN_TYPE, protocolDisplayOf, replyAuthor, type ActionClass, type ProtocolDisplay, } from './displays';
+export { isPapSignInTool, PAP_SIGN_IN_WORDS, readPapSignIn, safeSignInUrl, type PapSignInWaiting, } from './signIn';
+export { DIRECT_MAX, DIRECT_WORDS, directAnswerOf, directAuthor, directClient, openDirect, withDirectAnswer, type DirectAnswer, type DirectClient, type DirectClientOptions, type DirectLine, type DirectOpen, type DirectReply, type DirectTarget, } from './direct';
 export { agentRunClient, agentRuntimesUrlOf, appSessionsClient, RuntimeRefusal, type AgentRunClient, type AgentTurn, type AppSessionsClient, type RuntimeClientOptions, type SessionStart, type StreamOptions, } from './sessions';
 export type { ChatMessage } from '../types/messages';

package/lib/portable/index.js

@@ -24,5 +24,10 @@ export { PRESENCE_LINES, presenceOfConversation, presenceState, presenceToolOf,
 // One contract for every renderer of a conversation's components.
 export { ANSWER_BELOW, ANSWER_COMPLETE, composerOf, droppedWords, ENDED_WORDS, messageLabel, OPENING_WORDS, presenceLine, showsQuestion, stepLine, TOOL_STATUS_WORDS, toolLabel, } from './views';
 export { conversationFixture } from './fixtures';
+// The protocol displays a run's tool results carry (MOBILE M-037).
+export { DISPLAY_META_KEY, displayLine, displayOfToolResult, PAP_CONFIRM_TYPE, PAP_HANDOFF_TOOL, PAP_OUTCOME_TYPE, PAP_REPLIES_TYPE, PAP_SIGN_IN_TYPE, protocolDisplayOf, replyAuthor, } from './displays';
+export { isPapSignInTool, PAP_SIGN_IN_WORDS, readPapSignIn, safeSignInUrl, } from './signIn';
+// A Direct Conversation the person types in themselves (PAP_DATALAYER P-08, MOBILE M-038).
+export { DIRECT_MAX, DIRECT_WORDS, directAnswerOf, directAuthor, directClient, openDirect, withDirectAnswer, } from './direct';
 // The runtime's routes a native client drives.
 export { agentRunClient, agentRuntimesUrlOf, appSessionsClient, RuntimeRefusal, } from './sessions';

package/lib/portable/signIn.d.ts

@@ -0,0 +1,96 @@
+/**
+ * What the gateway's `pap_sign_in` tool answers, read and checked
+ * (AGENT_PROTOCOLS PI-56, PAP_DATALAYER P-03): the person signs in at a
+ * company themselves — on the company's page (`direct`), by entering a
+ * code there (`device`), or by typing what the company asks on Datalayer's
+ * own page (`mediated`), never in the conversation. The chat shows the link,
+ * the code and until when; the agent never sees what the person types. A
+ * business over PACT answers its `pact_sign_in` the same way (a `device`
+ * sign-in at the business).
+ *
+ * Pure: no React. A test reaches it without a chat around it.
+ *
+ * Kept in `portable/` (MOBILE M-037): Datalayer Mobile reads the same
+ * sign-in with the same checks; the web plugin re-exports it.
+ *
+ * @module portable/signIn
+ */
+/** A sign-in waiting for the person, as the card shows it. */
+export type PapSignInWaiting = {
+    mode: 'direct' | 'device' | 'mediated';
+    /** The company's page — Datalayer's own, for `mediated` — `https` only. */
+    open: string;
+    /** The page's domain, read from its address: what the person can trust. */
+    host: string;
+    /**
+     * The company's domain, when the gateway names it: for a bound `direct`
+     * sign-in the page opened is Datalayer's start link (PAP_DATALAYER P-04),
+     * which sends the person on to the company and takes them back only from it.
+     */
+    company?: string;
+    /** The code to enter, for `device`. */
+    code?: string;
+    /** Where the company sent a code, for `mediated`, when it did. */
+    sentTo?: string;
+    /** Until when, ISO 8601. */
+    expiresAt?: string;
+    /**
+     * What the company said it needs (its `authorization` event's scope,
+     * PAP_DATALAYER P-02): what the person is asked to allow there.
+     */
+    needs?: string[];
+};
+/** What the card says. */
+export declare const PAP_SIGN_IN_WORDS: {
+    readonly title: (host: string) => string;
+    readonly direct: "Open the company’s page through Datalayer, sign in there, and this conversation goes on once you are back.";
+    readonly device: "Open the company’s page and enter this code there.";
+    /** `mediated`: the page is Datalayer's, which names the company and asks what it asks. */
+    readonly mediatedTitle: (host: string) => string;
+    readonly mediated: "Open this page: it names the company and asks what the company needs. Type it there, never in this conversation.";
+    readonly sentTo: (to: string) => string;
+    readonly needs: (scopes: string[]) => string;
+    readonly open: (host: string) => string;
+    readonly code: "Your code";
+    readonly copy: "Copy the code";
+    readonly copied: "Copied";
+    readonly until: (at: string) => string;
+    readonly checkAgain: "I have signed in: check again";
+    readonly tellMe: "Tell me when you are done.";
+    readonly checkMessage: (host: string) => string;
+    readonly refused: "This sign-in link cannot be opened safely, so it is not shown.";
+    readonly qr: (host: string) => string;
+    /** Once the person's browser came back from the company (P-04), said under the card. */
+    readonly returned: {
+        readonly signed_in: (company: string) => string;
+        readonly denied: (company: string) => string;
+        readonly refused: (company: string) => string;
+    };
+};
+/**
+ * Where Datalayer's `/pap/signed-in` page says a Direct Sign-In came back
+ * (PAP_DATALAYER P-04): the card waiting for that company hears it in the
+ * person's tab, so the conversation goes on there.
+ */
+export declare const PAP_SIGN_IN_CHANNEL = "datalayer-pap-sign-in";
+/** How a Direct Sign-In came back. */
+export type PapSignInReturn = keyof typeof PAP_SIGN_IN_WORDS.returned;
+/** What a message on the channel says of this company's sign-in, or `null`: another company's, or not one. */
+export declare function signInReturnOf(message: unknown, company: string): PapSignInReturn | null;
+/**
+ * `pap_sign_in` — or a business's `pact_sign_in` (PI-56) — as the gateway
+ * names it with or without a prefix.
+ */
+export declare const PAP_SIGN_IN_TOOL: RegExp;
+/** Whether a tool is `pap_sign_in` or `pact_sign_in`, as the gateway names it with or without a prefix. */
+export declare const isPapSignInTool: (name: string) => boolean;
+/** The page's address, `https` only; `null` for anything else. */
+export declare function safeSignInUrl(open: unknown): URL | null;
+/**
+ * The sign-in waiting for the person, or why it is not shown: `null` for a
+ * result that is not one (another status: the chat's default row says it),
+ * `{ refused }` for a link that is not `https`.
+ */
+export declare function readPapSignIn(result: unknown): PapSignInWaiting | {
+    refused: string;
+} | null;

package/lib/portable/signIn.js

@@ -0,0 +1,148 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/** What the card says. */
+export const PAP_SIGN_IN_WORDS = {
+    title: (host) => `Sign in at ${host}`,
+    direct: 'Open the company’s page through Datalayer, sign in there, and this conversation goes on once you are back.',
+    device: 'Open the company’s page and enter this code there.',
+    /** `mediated`: the page is Datalayer's, which names the company and asks what it asks. */
+    mediatedTitle: (host) => `Sign in through ${host}`,
+    mediated: 'Open this page: it names the company and asks what the company needs. Type it there, never in this conversation.',
+    sentTo: (to) => `The company sent a code to ${to}.`,
+    needs: (scopes) => `It needs: ${scopes.join(', ')}.`,
+    open: (host) => `Open ${host}`,
+    code: 'Your code',
+    copy: 'Copy the code',
+    copied: 'Copied',
+    until: (at) => `Until ${new Date(at).toLocaleTimeString(undefined, { hour: '2-digit', minute: '2-digit' })}.`,
+    checkAgain: 'I have signed in: check again',
+    tellMe: 'Tell me when you are done.',
+    checkMessage: (host) => `I have signed in at ${host}. Please check again.`,
+    refused: 'This sign-in link cannot be opened safely, so it is not shown.',
+    qr: (host) => `A code to scan to open ${host} on your phone`,
+    /** Once the person's browser came back from the company (P-04), said under the card. */
+    returned: {
+        signed_in: (company) => `Signed in at ${company}: checking again.`,
+        denied: (company) => `You did not sign in at ${company}: ask again when you want to.`,
+        refused: (company) => `That sign-in at ${company} was refused, and nothing was kept: start it again here.`,
+    },
+};
+/**
+ * Where Datalayer's `/pap/signed-in` page says a Direct Sign-In came back
+ * (PAP_DATALAYER P-04): the card waiting for that company hears it in the
+ * person's tab, so the conversation goes on there.
+ */
+export const PAP_SIGN_IN_CHANNEL = 'datalayer-pap-sign-in';
+/** One OAuth scope token (RFC 6749 §3.3). */
+const SCOPE = /^[\x21\x23-\x5B\x5D-\x7E]{1,128}$/;
+const DOMAIN = /^(?=.{1,253}$)([a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z]{2,63}$/;
+/** What a message on the channel says of this company's sign-in, or `null`: another company's, or not one. */
+export function signInReturnOf(message, company) {
+    if (!message || typeof message !== 'object' || Array.isArray(message)) {
+        return null;
+    }
+    const said = message;
+    const outcome = said.outcome;
+    return said.company === company &&
+        (outcome === 'signed_in' || outcome === 'denied' || outcome === 'refused')
+        ? outcome
+        : null;
+}
+/**
+ * `pap_sign_in` — or a business's `pact_sign_in` (PI-56) — as the gateway
+ * names it with or without a prefix.
+ */
+export const PAP_SIGN_IN_TOOL = /(^|[_.:\-/])pa(?:p|ct)_sign_in$/;
+/** Whether a tool is `pap_sign_in` or `pact_sign_in`, as the gateway names it with or without a prefix. */
+export const isPapSignInTool = (name) => PAP_SIGN_IN_TOOL.test(name);
+/** An MCP result's own object: its structured content, or the JSON of its text. */
+function unwrapped(result) {
+    let value = result;
+    if (typeof value === 'string') {
+        try {
+            value = JSON.parse(value);
+        }
+        catch {
+            return null;
+        }
+    }
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        return null;
+    }
+    const data = value;
+    if (data.structuredContent && typeof data.structuredContent === 'object') {
+        return unwrapped(data.structuredContent);
+    }
+    if (Array.isArray(data.content)) {
+        const text = data.content.find(part => part?.type === 'text' && typeof part.text === 'string');
+        return text ? unwrapped(text.text) : null;
+    }
+    // FastMCP wraps a non-object answer as `{result: …}`.
+    if (data.result && typeof data.result === 'object' && !('status' in data)) {
+        return unwrapped(data.result);
+    }
+    return data;
+}
+/** The page's address, `https` only; `null` for anything else. */
+export function safeSignInUrl(open) {
+    if (typeof open !== 'string') {
+        return null;
+    }
+    try {
+        const url = new URL(open);
+        return url.protocol === 'https:' && url.hostname ? url : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * The sign-in waiting for the person, or why it is not shown: `null` for a
+ * result that is not one (another status: the chat's default row says it),
+ * `{ refused }` for a link that is not `https`.
+ */
+export function readPapSignIn(result) {
+    const data = unwrapped(result);
+    if (!data || data.status !== 'waiting_for_the_person') {
+        return null;
+    }
+    if (data.mode !== 'direct' &&
+        data.mode !== 'device' &&
+        data.mode !== 'mediated') {
+        return null;
+    }
+    const url = safeSignInUrl(data.open);
+    if (!url) {
+        return { refused: PAP_SIGN_IN_WORDS.refused };
+    }
+    if (data.mode === 'device' && (typeof data.code !== 'string' || !data.code)) {
+        return null;
+    }
+    // A bound Direct Sign-In opens Datalayer's start link: the card names the company the gateway
+    // names (`PapSignIn.company`); without one, the page's own domain is the company's.
+    const company = typeof data.company === 'string' && DOMAIN.test(data.company)
+        ? data.company
+        : '';
+    // What the company said it needs: scope tokens only, anything else not shown.
+    const needs = Array.isArray(data.needs)
+        ? data.needs.filter((scope) => typeof scope === 'string' && SCOPE.test(scope))
+        : [];
+    return {
+        mode: data.mode,
+        open: url.toString(),
+        host: url.hostname,
+        ...(company ? { company } : {}),
+        ...(typeof data.code === 'string' && data.code ? { code: data.code } : {}),
+        ...(data.mode === 'mediated' &&
+            typeof data.sent_to === 'string' &&
+            data.sent_to
+            ? { sentTo: data.sent_to }
+            : {}),
+        ...(typeof data.expires_at === 'string' && data.expires_at
+            ? { expiresAt: data.expires_at }
+            : {}),
+        ...(needs.length > 0 ? { needs } : {}),
+    };
+}