@datalayer/agent-runtimes 1.5.25 → 1.5.26

package/lib/portable/index.d.ts

@@ -18,5 +18,7 @@ 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 { SIGN_IN_POLL_MS, SIGN_IN_STATUS_PATH, signInStandsOf, signInStatusClient, type SignInStands, } from './signInStatus';
+export { emptyFields, fieldProblems, MAX_VALUE_LENGTH, PROTECTED_INPUT_WORDS, protectedInputClient, protectedRequestOf, ProtectedRequestGone, sentWords, submitBody, submitWords, ticketComplete, ticketOfPage, type ProtectedField, type ProtectedRequest, } from './protectedInput';
 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

@@ -29,5 +29,9 @@ export { DISPLAY_META_KEY, displayLine, displayOfToolResult, PAP_CONFIRM_TYPE, P
 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';
+// How a sign-in under way stands, asked by the person's own client (MOBILE M-039).
+export { SIGN_IN_POLL_MS, SIGN_IN_STATUS_PATH, signInStandsOf, signInStatusClient, } from './signInStatus';
+// What a company asks the person to type in a mediated sign-in, sent with its one-use ticket (MOBILE M-039).
+export { emptyFields, fieldProblems, MAX_VALUE_LENGTH, PROTECTED_INPUT_WORDS, protectedInputClient, protectedRequestOf, ProtectedRequestGone, sentWords, submitBody, submitWords, ticketComplete, ticketOfPage, } from './protectedInput';
 // The runtime's routes a native client drives.
 export { agentRunClient, agentRuntimesUrlOf, appSessionsClient, RuntimeRefusal, } from './sessions';

package/lib/portable/protectedInput.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Mediated sign-in (PAP_DATALAYER P-03, MOBILE M-039): a personal agent signs
+ * the person in at a company that asks for what only the person knows — a
+ * name and a password, or a code the company sent them. The person types it
+ * on a page of their own Datalayer client, signed in to Datalayer; it goes
+ * to IAM with the one-use protected ticket the sign-in named
+ * (`/pap/my/protected/{ticket}`), which passes it to the company once. The
+ * agent never sees it. The Studio's `/pap/sign-in` and Datalayer Mobile use
+ * this one module.
+ *
+ * Pure but for the given `fetch`: nothing typed is kept — not in an address,
+ * not in storage, not in an error.
+ *
+ * @module portable/protectedInput
+ */
+/** One thing the company asks the person to type. */
+export type ProtectedField = {
+    name: string;
+    label: string;
+    /** Typed as a password: hidden, never filled in by the browser. */
+    secret: boolean;
+};
+/** What the company asks, of whom, until when. */
+export type ProtectedRequest = {
+    companyName: string;
+    /** The company's own domain: what the person can check. */
+    companyDomain: string;
+    purpose: 'credentials' | 'one_time_code';
+    fields: ProtectedField[];
+    /** Where the company sent its code, when it did. */
+    sentTo: string | null;
+    expiresAt: string;
+};
+/** What IAM keeps of one field, at most. */
+export declare const MAX_VALUE_LENGTH = 1024;
+/** What the page says (checked against the vocabulary). */
+export declare const PROTECTED_INPUT_WORDS: {
+    readonly title: (company: string) => string;
+    readonly intro: (company: string) => string;
+    readonly asks: "Who asks";
+    readonly where: "Where";
+    readonly whereHint: "The company’s address: the part you can check.";
+    readonly sentCode: (company: string, sentTo: string) => string;
+    readonly sentCodeSomewhere: (company: string) => string;
+    readonly code: "Code";
+    readonly signIn: (company: string) => string;
+    readonly sendCode: "Send the code";
+    readonly sending: "Sending…";
+    readonly fillEvery: "Fill in every field.";
+    readonly tooLong: (label: string) => string;
+    readonly done: "Done. Go back to your conversation: the agent continues once it checks.";
+    readonly expires: (at: string) => string;
+    readonly reading: "Reading the request…";
+    readonly gone: "This request is unknown, already answered or expired. Ask your personal agent to start again.";
+    readonly incomplete: "This link is incomplete: it names no request. Start again from your personal agent.";
+    readonly signedOut: "Sign in to Datalayer first.";
+};
+/** Whether a link names a request. */
+export declare const ticketComplete: (ticket: string) => boolean;
+/** Raised when IAM does not know the request (unknown, answered or expired): the page says only that. */
+export declare class ProtectedRequestGone extends Error {
+    constructor();
+}
+/** IAM's answer read whole, or refused with a sentence: no default. */
+export declare function protectedRequestOf(raw: unknown): ProtectedRequest;
+/** The fields still empty, by name: the form is sent only when there is none. */
+export declare const emptyFields: (request: Pick<ProtectedRequest, "fields">, values: Record<string, string>) => string[];
+/** What keeps the form from being sent, in sentences; none when it can be. Never what was typed. */
+export declare function fieldProblems(request: Pick<ProtectedRequest, 'fields'>, values: Record<string, string>): string[];
+/** The words on the one button. */
+export declare const submitWords: (request: Pick<ProtectedRequest, "purpose" | "companyName">) => string;
+/** What the code page says of where the code went. */
+export declare const sentWords: (request: Pick<ProtectedRequest, "companyName" | "sentTo">) => string;
+/**
+ * The body sent: exactly the fields asked, none empty, as typed. A code is
+ * sent without its spaces; a password, exactly as typed.
+ */
+export declare function submitBody(request: Pick<ProtectedRequest, 'fields' | 'purpose'>, values: Record<string, string>): {
+    values: Record<string, string>;
+};
+/** The ticket a mediated sign-in page names (`…?ticket=`), or `''`. */
+export declare function ticketOfPage(open: string): string;
+/** IAM's protected-input routes, with the person's own sign-in. */
+export declare function protectedInputClient({ iamUrl, getAccessToken, fetch: fetcher, }: {
+    iamUrl: string;
+    getAccessToken: () => string | undefined;
+    fetch: typeof fetch;
+}): {
+    /** What the company asks; reading it does not use the request up. */
+    read: (ticket: string) => Promise<ProtectedRequest>;
+    /** What the person typed, sent once to IAM. */
+    send: (ticket: string, request: Pick<ProtectedRequest, "fields" | "purpose">, values: Record<string, string>) => Promise<void>;
+};

package/lib/portable/protectedInput.js

@@ -0,0 +1,186 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/** What IAM keeps of one field, at most. */
+export const MAX_VALUE_LENGTH = 1024;
+/** What the page says (checked against the vocabulary). */
+export const PROTECTED_INPUT_WORDS = {
+    title: (company) => `Sign in at ${company}`,
+    intro: (company) => `Your personal agent is signing you in at ${company}, which asks for what only you know. Type it here: Datalayer passes it to ${company} once, and your agent never sees it.`,
+    asks: 'Who asks',
+    where: 'Where',
+    whereHint: 'The company’s address: the part you can check.',
+    sentCode: (company, sentTo) => `${company} sent a code to ${sentTo}.`,
+    sentCodeSomewhere: (company) => `${company} sent you a code.`,
+    code: 'Code',
+    signIn: (company) => `Sign in at ${company}`,
+    sendCode: 'Send the code',
+    sending: 'Sending…',
+    fillEvery: 'Fill in every field.',
+    tooLong: (label) => `${label} is longer than ${MAX_VALUE_LENGTH} characters.`,
+    done: 'Done. Go back to your conversation: the agent continues once it checks.',
+    expires: (at) => `This request ends at ${new Date(at).toLocaleTimeString(undefined, { hour: '2-digit', minute: '2-digit' })}.`,
+    reading: 'Reading the request…',
+    gone: 'This request is unknown, already answered or expired. Ask your personal agent to start again.',
+    incomplete: 'This link is incomplete: it names no request. Start again from your personal agent.',
+    signedOut: 'Sign in to Datalayer first.',
+};
+const TICKET = /^[A-Za-z0-9_-]{8,256}$/;
+const FIELD_NAME = /^[A-Za-z][A-Za-z0-9_.-]{0,63}$/;
+/** Whether a link names a request. */
+export const ticketComplete = (ticket) => TICKET.test(ticket.trim());
+/** Raised when IAM does not know the request (unknown, answered or expired): the page says only that. */
+export class ProtectedRequestGone extends Error {
+    constructor() {
+        super(PROTECTED_INPUT_WORDS.gone);
+        this.name = 'ProtectedRequestGone';
+    }
+}
+/** IAM's answer read whole, or refused with a sentence: no default. */
+export function protectedRequestOf(raw) {
+    const refused = () => new Error('The request could not be read.');
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+        throw refused();
+    }
+    const data = raw;
+    if (typeof data.company_name !== 'string' ||
+        typeof data.company_domain !== 'string' ||
+        !data.company_domain ||
+        (data.purpose !== 'credentials' && data.purpose !== 'one_time_code') ||
+        !Array.isArray(data.fields) ||
+        data.fields.length === 0 ||
+        data.fields.length > 10 ||
+        typeof data.expires_at !== 'string' ||
+        !(data.sent_to === null ||
+            data.sent_to === undefined ||
+            typeof data.sent_to === 'string')) {
+        throw refused();
+    }
+    const names = new Set();
+    const fields = data.fields.map(item => {
+        if (!item || typeof item !== 'object' || Array.isArray(item)) {
+            throw refused();
+        }
+        const entry = item;
+        if (typeof entry.name !== 'string' ||
+            !FIELD_NAME.test(entry.name) ||
+            names.has(entry.name) ||
+            typeof entry.label !== 'string' ||
+            typeof entry.secret !== 'boolean') {
+            throw refused();
+        }
+        names.add(entry.name);
+        return {
+            name: entry.name,
+            label: entry.label || entry.name,
+            secret: entry.secret,
+        };
+    });
+    if (data.purpose === 'one_time_code' && fields.length !== 1) {
+        throw refused();
+    }
+    return {
+        companyName: data.company_name || data.company_domain,
+        companyDomain: data.company_domain,
+        purpose: data.purpose,
+        fields,
+        sentTo: typeof data.sent_to === 'string' && data.sent_to ? data.sent_to : null,
+        expiresAt: data.expires_at,
+    };
+}
+/** The fields still empty, by name: the form is sent only when there is none. */
+export const emptyFields = (request, values) => request.fields
+    .filter(field => !(values[field.name] ?? '').trim())
+    .map(field => field.name);
+/** What keeps the form from being sent, in sentences; none when it can be. Never what was typed. */
+export function fieldProblems(request, values) {
+    const problems = [];
+    if (emptyFields(request, values).length) {
+        problems.push(PROTECTED_INPUT_WORDS.fillEvery);
+    }
+    for (const field of request.fields) {
+        if ((values[field.name] ?? '').length > MAX_VALUE_LENGTH) {
+            problems.push(PROTECTED_INPUT_WORDS.tooLong(field.label));
+        }
+    }
+    return problems;
+}
+/** The words on the one button. */
+export const submitWords = (request) => request.purpose === 'one_time_code'
+    ? PROTECTED_INPUT_WORDS.sendCode
+    : PROTECTED_INPUT_WORDS.signIn(request.companyName);
+/** What the code page says of where the code went. */
+export const sentWords = (request) => request.sentTo
+    ? PROTECTED_INPUT_WORDS.sentCode(request.companyName, request.sentTo)
+    : PROTECTED_INPUT_WORDS.sentCodeSomewhere(request.companyName);
+/**
+ * The body sent: exactly the fields asked, none empty, as typed. A code is
+ * sent without its spaces; a password, exactly as typed.
+ */
+export function submitBody(request, values) {
+    const problems = fieldProblems(request, values);
+    if (problems.length) {
+        throw new Error(problems.join(' '));
+    }
+    const sent = {};
+    for (const field of request.fields) {
+        const typed = values[field.name];
+        sent[field.name] =
+            request.purpose === 'one_time_code' ? typed.replace(/\s+/g, '') : typed;
+    }
+    return { values: sent };
+}
+/** The ticket a mediated sign-in page names (`…?ticket=`), or `''`. */
+export function ticketOfPage(open) {
+    try {
+        const ticket = new URL(open).searchParams.get('ticket') ?? '';
+        return ticketComplete(ticket) ? ticket.trim() : '';
+    }
+    catch {
+        return '';
+    }
+}
+/** IAM's protected-input routes, with the person's own sign-in. */
+export function protectedInputClient({ iamUrl, getAccessToken, fetch: fetcher, }) {
+    const address = (ticket) => {
+        if (!iamUrl) {
+            throw new Error('Datalayer’s sign-in service is not configured.');
+        }
+        return `${iamUrl.replace(/\/+$/, '')}/api/iam/v1/pap/my/protected/${encodeURIComponent(ticket.trim())}`;
+    };
+    const headers = () => {
+        const token = getAccessToken();
+        return {
+            'Content-Type': 'application/json',
+            ...(token ? { Authorization: `Bearer ${token}` } : {}),
+        };
+    };
+    /** IAM's refusal in its own sentence; never what was typed. */
+    const answered = async (response, what) => {
+        const body = (await response.json().catch(() => ({})));
+        if (response.status === 404) {
+            throw new ProtectedRequestGone();
+        }
+        if (!response.ok) {
+            throw new Error(`${what}: ${typeof body.detail === 'string' ? body.detail : response.status}`);
+        }
+        return body;
+    };
+    return {
+        /** What the company asks; reading it does not use the request up. */
+        read: async (ticket) => protectedRequestOf(await answered(await fetcher(address(ticket), { headers: headers() }), 'The request could not be read')),
+        /** What the person typed, sent once to IAM. */
+        send: async (ticket, request, values) => {
+            const body = submitBody(request, values);
+            const answer = await answered(await fetcher(address(ticket), {
+                method: 'POST',
+                headers: headers(),
+                body: JSON.stringify(body),
+            }), 'It was not sent');
+            if (answer.kept !== true) {
+                throw new Error('It was not sent: the answer does not say it was kept.');
+            }
+        },
+    };
+}

package/lib/portable/signInStatus.d.ts

@@ -0,0 +1,37 @@
+/**
+ * How a sign-in under way stands, asked by the person's own client (MOBILE
+ * M-039): the gateway's `GET /api/mcp/v1/pap/sign-in?app_uid&company`, with
+ * the person's own sign-in, finishes what can be finished — a Direct return
+ * IAM bound to their browser and the company asked, a Device code the
+ * company confirmed — and says where it stands.
+ *
+ * A continuation is accepted only when it is bound: the answer names the
+ * application and the company the card was for, and a verified issuer. The
+ * client then goes on in the same conversation (its session), once.
+ *
+ * Pure but for the given `fetch`.
+ *
+ * @module portable/signInStatus
+ */
+/** Where the gateway answers how a sign-in stands. */
+export declare const SIGN_IN_STATUS_PATH = "/api/mcp/v1/pap/sign-in";
+/** How often a client asks while a sign-in waits, and never past its expiry. */
+export declare const SIGN_IN_POLL_MS = 5000;
+export type SignInStands = {
+    appUid: string;
+    company: string;
+    issuer: string;
+    status: 'pending' | 'signed_in' | 'refused' | 'denied' | 'not_started' | 'other';
+    reason: string;
+};
+/** The gateway's answer, or `null` when it does not bind to this application and company. */
+export declare function signInStandsOf(raw: unknown, expected: {
+    appUid: string;
+    company: string;
+}): SignInStands | null;
+/** Asks how a sign-in stands; `null` for none under way (404) or an answer that does not bind. */
+export declare function signInStatusClient({ baseUrl, getAccessToken, fetch: fetcher, }: {
+    baseUrl: string;
+    getAccessToken: () => string | undefined;
+    fetch: typeof fetch;
+}): (appUid: string, company: string) => Promise<SignInStands | null>;

package/lib/portable/signInStatus.js

@@ -0,0 +1,74 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * How a sign-in under way stands, asked by the person's own client (MOBILE
+ * M-039): the gateway's `GET /api/mcp/v1/pap/sign-in?app_uid&company`, with
+ * the person's own sign-in, finishes what can be finished — a Direct return
+ * IAM bound to their browser and the company asked, a Device code the
+ * company confirmed — and says where it stands.
+ *
+ * A continuation is accepted only when it is bound: the answer names the
+ * application and the company the card was for, and a verified issuer. The
+ * client then goes on in the same conversation (its session), once.
+ *
+ * Pure but for the given `fetch`.
+ *
+ * @module portable/signInStatus
+ */
+/** Where the gateway answers how a sign-in stands. */
+export const SIGN_IN_STATUS_PATH = '/api/mcp/v1/pap/sign-in';
+/** How often a client asks while a sign-in waits, and never past its expiry. */
+export const SIGN_IN_POLL_MS = 5000;
+const STATUSES = [
+    'pending',
+    'signed_in',
+    'refused',
+    'denied',
+    'not_started',
+];
+/** The gateway's answer, or `null` when it does not bind to this application and company. */
+export function signInStandsOf(raw, expected) {
+    const data = raw && typeof raw === 'object' && !Array.isArray(raw)
+        ? raw
+        : null;
+    if (!data ||
+        data.app_uid !== expected.appUid ||
+        typeof data.company !== 'string' ||
+        data.company.toLowerCase() !== expected.company.toLowerCase() ||
+        typeof data.issuer !== 'string' ||
+        !data.issuer.startsWith('https://')) {
+        return null;
+    }
+    return {
+        appUid: expected.appUid,
+        company: data.company,
+        issuer: data.issuer,
+        status: STATUSES.find(status => status === data.status) ?? 'other',
+        reason: typeof data.reason === 'string' ? data.reason : '',
+    };
+}
+/** Asks how a sign-in stands; `null` for none under way (404) or an answer that does not bind. */
+export function signInStatusClient({ baseUrl, getAccessToken, fetch: fetcher, }) {
+    return async (appUid, company) => {
+        const token = getAccessToken();
+        if (!token) {
+            return null;
+        }
+        const query = new URLSearchParams({ app_uid: appUid, company });
+        const response = await fetcher(`${baseUrl.replace(/\/+$/, '')}${SIGN_IN_STATUS_PATH}?${query.toString()}`, {
+            headers: {
+                Authorization: `Bearer ${token}`,
+                Accept: 'application/json',
+            },
+        });
+        if (response.status === 404) {
+            return null;
+        }
+        if (!response.ok) {
+            throw new Error(`How the sign-in at ${company} stands could not be read (${response.status}).`);
+        }
+        return signInStandsOf(await response.json(), { appUid, company });
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@datalayer/agent-runtimes",
-    "version": "1.5.25",
+    "version": "1.5.26",
     "type": "module",
     "workspaces": [
         ".",