tapline-host 1.5.0 → 1.6.1

package/dist/accounts.d.ts

@@ -0,0 +1,72 @@
+import { z } from "zod";
+export declare const accountsFileSchema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    accounts: z.ZodRecord<z.ZodString, z.ZodObject<{
+        username: z.ZodOptional<z.ZodString>;
+        password: z.ZodOptional<z.ZodString>;
+        passcode: z.ZodOptional<z.ZodString>;
+        apps: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type AccountsFile = z.infer<typeof accountsFileSchema>;
+export type AccountField = "username" | "password";
+export type AccountResolved = {
+    ok: true;
+    value: string;
+} | {
+    ok: false;
+    code: "not_found" | "bad_params";
+    message: string;
+};
+export interface AccountStore {
+    /** The accounts' names, never their values. */
+    names(): string[];
+    /** One value of an account, for an app. */
+    resolve(name: string, field: AccountField, appId: string): AccountResolved;
+    /** Replaces every username with `<tester2's username>` and every password with `<tester2's password>`. */
+    redact(text: string): string;
+}
+/** What the accounts file gave: its accounts, or why none were loaded (the git message). */
+export type AccountsLoad = {
+    store: AccountStore;
+} | {
+    store: null;
+    blocked: string;
+};
+export interface GitProbe {
+    /** Whether the folder is inside a git work tree. */
+    insideWorkTree(dir: string): Promise<boolean>;
+    /** Whether git ignores the file (a tracked file counts as not ignored). */
+    ignored(file: string): Promise<boolean>;
+}
+/** The real probe: the user's own git, run without a shell. When git can't run, a `.git` above the file counts as a work tree. */
+export declare const realGitProbe: GitProbe;
+/** What the user is told wherever the accounts option is described (the parameter text, `--help`, `doctor`). */
+export declare const ACCOUNTS_WARNING = "A password stays out of pictures only while its field is secure; a \"show password\" toggle shows it. Keep the accounts file outside the folders the agent may read.";
+/** The refusal's words, for the first answer, `doctor` and every use. */
+export declare function blockedMessage(file: string): string;
+export declare function accountStore(file: AccountsFile): AccountStore;
+/**
+ * Reads the accounts file. Inside a git work tree that doesn't ignore it, nothing is read or loaded. A file that can't
+ * be read or isn't the format throws a plain message that never quotes the file (it holds secrets).
+ */
+export declare function loadAccounts(file: string, probe?: GitProbe): Promise<AccountsLoad>;
+/**
+ * Scrubs every string in a JSON value (an app's answer), keeping its shape. Property names are scrubbed too; two names
+ * that come out the same stay apart with a numbered suffix.
+ */
+export declare function redactValue(value: unknown, redact: (text: string) => string): unknown;
+export type AccountText = {
+    ok: true;
+    text: string;
+    field: AccountField | null;
+} | {
+    ok: false;
+    code: "not_found" | "bad_params";
+    message: string;
+};
+/**
+ * `${account.username}` or `${account.password}` becomes the value, but only when it is the whole text: joined with
+ * other text it could get a password past the secure-field rule. Text without a placeholder passes unchanged (field null).
+ */
+export declare function substituteAccount(text: string, store: AccountStore, name: string | undefined, appId: string): AccountText;

package/dist/accounts.js

@@ -0,0 +1,208 @@
+import { execFile } from "node:child_process";
+import { existsSync, readFileSync, realpathSync } from "node:fs";
+import { dirname, join, parse, resolve } from "node:path";
+import { z } from "zod";
+/**
+ * Test accounts (AGENT-TOOLS 1.13 §18.6). The file holds real test credentials, so this module is built to keep them
+ * from the agent: the file is refused inside a git work tree that doesn't ignore it, a value is typed only as the
+ * whole text of a step, and `redact` scrubs every value from what the app sends back.
+ */
+const ACCOUNT_NAME = /^[\w.-]{1,60}$/;
+// A shorter value would be scrubbed out of unrelated text. The message quotes no value.
+const SHORT = "must be at least 3 characters, so scrubbing it can't garble other text";
+const accountSchema = z.object({
+    username: z.string().min(3, SHORT).optional(),
+    password: z.string().min(3, SHORT).optional(),
+    /** Tapwright's: the phone's passcode. Tapline loads it without complaint and never types it. */
+    passcode: z.string().min(1).optional(),
+    apps: z.array(z.string().min(1)).optional(),
+});
+export const accountsFileSchema = z.object({
+    version: z.literal(1),
+    accounts: z.record(z.string().regex(ACCOUNT_NAME, "account names use letters, digits, '.', '_' and '-'"), accountSchema),
+});
+function git(args, cwd) {
+    return new Promise((done) => {
+        execFile("git", args, { cwd, timeout: 10_000, windowsHide: true, encoding: "utf8" }, (error, stdout) => {
+            if (error === null)
+                return done({ code: 0, stdout });
+            const code = error.code;
+            done({ code: typeof code === "number" ? code : null, stdout: "" });
+        });
+    });
+}
+/** Whether a folder or one above it holds a `.git`: the answer when git itself can't be run. */
+function hasGitAbove(dir) {
+    let at = resolve(dir);
+    for (;;) {
+        if (existsSync(join(at, ".git")))
+            return true;
+        const up = dirname(at);
+        if (up === at || parse(at).root === at)
+            return false;
+        at = up;
+    }
+}
+/** The real probe: the user's own git, run without a shell. When git can't run, a `.git` above the file counts as a work tree. */
+export const realGitProbe = {
+    async insideWorkTree(dir) {
+        const out = await git(["rev-parse", "--is-inside-work-tree"], dir);
+        return out.code === 0 ? out.stdout.trim() === "true" : hasGitAbove(dir);
+    },
+    async ignored(file) {
+        return (await git(["check-ignore", "-q", "--", file], dirname(file))).code === 0;
+    },
+};
+/** What the user is told wherever the accounts option is described (the parameter text, `--help`, `doctor`). */
+export const ACCOUNTS_WARNING = "A password stays out of pictures only while its field is secure; a \"show password\" toggle shows it. Keep the accounts file outside the folders the agent may read.";
+/** The refusal's words, for the first answer, `doctor` and every use. */
+export function blockedMessage(file) {
+    return `accounts file is inside the git repo at ${file} and not ignored; move it or add it to .gitignore.`;
+}
+/** The invisible direction marks the app strips from text (react-native-tapline's `displayText`). */
+const DIRECTION_MARKS = /[‎‏‪-‮⁦-⁩]/g;
+/**
+ * The shapes a value can take on its way back: as it is, inside a JSON string, in a URL (percent or form encoded), and
+ * as the app's `normalizeText` leaves it (direction marks gone, whitespace collapsed and trimmed).
+ */
+function variantsOf(value) {
+    const normalized = value.replace(DIRECTION_MARKS, "").replace(/\s+/g, " ").trim();
+    const forms = new Set();
+    for (const base of [value, normalized]) {
+        forms.add(base);
+        forms.add(JSON.stringify(base).slice(1, -1));
+        const percent = encodeURIComponent(base);
+        forms.add(percent);
+        forms.add(percent.replace(/%20/g, "+"));
+        // URLSearchParams encodes more than encodeURIComponent does (`~` becomes %7E).
+        forms.add(new URLSearchParams({ k: base }).toString().slice(2));
+    }
+    return [...forms].filter((form) => form !== "");
+}
+/** Longest variants first, so a value that holds another is scrubbed whole. */
+function scrubber(accounts) {
+    const pairs = [];
+    for (const [name, account] of Object.entries(accounts)) {
+        if (account.username !== undefined)
+            for (const form of variantsOf(account.username))
+                pairs.push([form, `<${name}'s username>`]);
+        if (account.password !== undefined)
+            for (const form of variantsOf(account.password))
+                pairs.push([form, `<${name}'s password>`]);
+    }
+    pairs.sort((a, b) => b[0].length - a[0].length);
+    return (text) => {
+        let out = text;
+        for (const [value, token] of pairs)
+            if (out.includes(value))
+                out = out.split(value).join(token);
+        return out;
+    };
+}
+export function accountStore(file) {
+    const accounts = file.accounts;
+    const scrub = scrubber(accounts);
+    const names = Object.keys(accounts);
+    const list = () => (names.length === 0 ? "the accounts file has none" : `the accounts are ${names.join(", ")}`);
+    return {
+        names: () => [...names],
+        redact: scrub,
+        resolve(name, field, appId) {
+            const account = Object.prototype.hasOwnProperty.call(accounts, name) ? accounts[name] : undefined;
+            if (account === undefined)
+                return { ok: false, code: "not_found", message: `no account "${name}"; ${list()}.` };
+            if (account.apps !== undefined && !account.apps.includes(appId)) {
+                return { ok: false, code: "bad_params", message: `account "${name}" isn't for this app (${appId}); it is for ${account.apps.join(", ")}.` };
+            }
+            const value = account[field];
+            if (value === undefined)
+                return { ok: false, code: "bad_params", message: `account "${name}" has no ${field}.` };
+            return { ok: true, value };
+        },
+    };
+}
+/**
+ * Reads the accounts file. Inside a git work tree that doesn't ignore it, nothing is read or loaded. A file that can't
+ * be read or isn't the format throws a plain message that never quotes the file (it holds secrets).
+ */
+export async function loadAccounts(file, probe = realGitProbe) {
+    const path = resolve(file);
+    if (!existsSync(path))
+        throw new Error(`the accounts file ${path} doesn't exist`);
+    // Through a symlink or a junction the file may really sit in a repo: ask about where it is.
+    let real = path;
+    try {
+        real = realpathSync(path);
+    }
+    catch {
+        // the path stands
+    }
+    // A `.git` folder in the path is a repo's own files, which no .gitignore covers.
+    const inGitDir = real.split(/[\\/]/).includes(".git");
+    if (inGitDir || ((await probe.insideWorkTree(dirname(real))) && !(await probe.ignored(real)))) {
+        return { store: null, blocked: blockedMessage(path) };
+    }
+    let json;
+    try {
+        json = JSON.parse(readFileSync(real, "utf8"));
+    }
+    catch {
+        // Node's own message quotes part of the text, and this file holds passwords.
+        throw new Error(`the accounts file ${path} isn't valid JSON`);
+    }
+    const parsed = accountsFileSchema.safeParse(json);
+    if (!parsed.success) {
+        const why = parsed.error.issues.map((issue) => `${issue.path.join(".") || "file"}: ${issue.message}`).join("; ");
+        throw new Error(`the accounts file ${path} isn't the right format: ${why}`);
+    }
+    return { store: accountStore(parsed.data) };
+}
+/**
+ * Scrubs every string in a JSON value (an app's answer), keeping its shape. Property names are scrubbed too; two names
+ * that come out the same stay apart with a numbered suffix.
+ */
+export function redactValue(value, redact) {
+    if (typeof value === "string")
+        return redact(value);
+    if (Array.isArray(value))
+        return value.map((item) => redactValue(item, redact));
+    if (typeof value === "object" && value !== null) {
+        const out = {};
+        for (const [key, item] of Object.entries(value)) {
+            const base = redact(key);
+            let name = base;
+            for (let n = 2; Object.prototype.hasOwnProperty.call(out, name); n++)
+                name = `${base} #${n}`;
+            // defineProperty keeps a name like "__proto__" an ordinary key.
+            Object.defineProperty(out, name, { value: redactValue(item, redact), enumerable: true, writable: true, configurable: true });
+        }
+        return out;
+    }
+    return value;
+}
+const WHOLE = /^\$\{account\.(\w+)\}$/;
+/**
+ * `${account.username}` or `${account.password}` becomes the value, but only when it is the whole text: joined with
+ * other text it could get a password past the secure-field rule. Text without a placeholder passes unchanged (field null).
+ */
+export function substituteAccount(text, store, name, appId) {
+    const whole = WHOLE.exec(text);
+    if (whole === null) {
+        if (text.includes("${account."))
+            return { ok: false, code: "bad_params", message: "an account value is the whole text of a step, not part of one." };
+        return { ok: true, text, field: null };
+    }
+    const field = whole[1];
+    if (field === "passcode") {
+        return { ok: false, code: "bad_params", message: "an account's passcode is typed only by Tapwright on a locked phone's keypad; Tapline never types it." };
+    }
+    if (field !== "username" && field !== "password") {
+        return { ok: false, code: "bad_params", message: `\${account.${field ?? ""}} isn't a value an account has; use \${account.username} or \${account.password}.` };
+    }
+    if (name === undefined) {
+        return { ok: false, code: "bad_params", message: `name the account: add "account": "<name>" (${store.names().length === 0 ? "the accounts file has none" : `the accounts are ${store.names().join(", ")}`}).` };
+    }
+    const resolved = store.resolve(name, field, appId);
+    return resolved.ok ? { ok: true, text: resolved.value, field } : resolved;
+}
+//# sourceMappingURL=accounts.js.map

package/dist/accounts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"accounts.js","sourceRoot":"","sources":["../src/accounts.ts"],"names":[],"mappings":"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"}

package/dist/actionlog.d.ts

@@ -14,7 +14,14 @@ export interface ActionLogEntry {
     ok: boolean;
     code?: string;
     reason?: string;
+    /** The time in the tool, in ms: an action's own, a read's whole call (AGENT-TOOLS 1.13 §16.1). `t` is when it began. */
     ms?: number;
+    /** 2: `t` is when the call began and `ms` its time. Older entries stamped the end, so the Time line leaves them out. */
+    v?: 2;
+    /** `"call"` when the call came through the thin call, a new process each time (§18.10). */
+    via?: "call";
+    /** `"fast"` when fast-forwarded animations were on while the call ran (PLAN-1.6 F4); the report says how many calls. */
+    animations?: "fast";
     app?: string;
     batch?: {
         id: string;
@@ -22,6 +29,8 @@ export interface ActionLogEntry {
     };
     dry_run?: boolean;
     confirmed?: boolean;
+    /** Where a person's OK came from: the host's dialog or the live view (AGENT-TOOLS 1.13 §11.3). */
+    confirmed_by?: "chat" | "live view";
     /** For typing: how many characters, never the text. */
     chars?: number;
     /** AGENT-TOOLS 1.11 §16.1: `"read"` for a call that isn't an action (look, wait_for, logs, ...). */
@@ -51,6 +60,17 @@ export interface ActionLogEntry {
      * Set on the call's action entries, so a report counts the call as failed (Codex review of 1.4.0).
      */
     call_failed?: string;
+    /** A `compare_screen` that matched under its threshold but named changed clusters (AGENT-TOOLS 1.13.1 item 2). */
+    matched_with_changes?: boolean;
+    /**
+     * A touch that took the app from one place to another: their names (the map's own, never screen text), and whether the map
+     * already held a proven road between them. The report uses it to say a way was known (AGENT-TOOLS 1.13 16.1).
+     */
+    way?: {
+        from: string;
+        to: string;
+        known: boolean;
+    };
 }
 export declare const LOG_KEEP_DAYS = 14;
 export declare class ActionLog {

package/dist/actionlog.js.map

@@ -1 +1 @@
-{"version":3,"file":"actionlog.js","sourceRoot":"","sources":["../src/actionlog.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"actionlog.js","sourceRoot":"","sources":["../src/actionlog.ts"],"names":[],"mappings":"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"}

package/dist/animations.d.ts

@@ -0,0 +1,39 @@
+import type { TaplineHost } from "./server.js";
+/**
+ * Fast-forwarded animations on the host side (PLAN-1.6 F4, AGENT-TOOLS 1.13 18.12). The app does the work (its
+ * `animations` command and its three layers); the host remembers which sessions it switched on, so that it can
+ * put them back for a measurement and when the session ends. State is kept per host, not per tools object, because
+ * several agents' tools share one app.
+ */
+/** The line every answer carries while fast animations are on (the shape of the network line). */
+export declare const ANIMATIONS_LINE = "Animations: fast (Tapline).";
+/** What a call says when it could not be run with animations normal. */
+export declare const ANIMATIONS_NOT_PAUSED_NOTE = "Note: animations could not be set to normal for this call; it ran with fast animations.";
+/** What a call that ran with animations paused says at its end. */
+export declare const ANIMATIONS_PAUSED_NOTE = "Note: animations were normal during this call.";
+/** Whether the host switched fast animations on for this session and they are meant to be on. */
+export declare function animationsOn(host: TaplineHost, sessionId: string): boolean;
+/** Records what the app's `animations` command was last set to. */
+export declare function noteAnimations(host: TaplineHost, sessionId: string, speed: "fast" | "normal"): void;
+/** Waits while a measurement holds the session at normal: an explicit switch to fast must not land inside it. */
+export declare function afterPause(host: TaplineHost, sessionId: string): Promise<void>;
+/**
+ * Runs `run` with animations normal when they are on for the session, and puts them back after, whatever `run` does.
+ * `paused` is true when they were on and are normal for this call; `failed` when the switch to normal did not go through
+ * (the call then ran fast, and says so). Pauses overlapping in one session are counted: normal is sent by the first and
+ * fast comes back when the last one ends.
+ */
+export declare function withNormalAnimations<T>(host: TaplineHost, sessionId: string | undefined, run: () => Promise<T>): Promise<{
+    value: T;
+    paused: boolean;
+    failed: boolean;
+}>;
+/**
+ * Puts one session back to normal for good (a journey in a user's eyes starts). False when they were not on, or when
+ * the app refused the switch: the session then stays tracked as fast, so nothing reports animations as normal.
+ */
+export declare function endAnimations(host: TaplineHost, sessionId: string): Promise<boolean>;
+/** The session ends: every session this host switched to fast goes back to normal. A session that is gone is skipped. */
+export declare function restoreAnimations(host: TaplineHost): Promise<void>;
+/** Forgets a session that ended (the app restores itself on a disconnect). */
+export declare function forgetAnimations(host: TaplineHost, sessionId: string): void;

package/dist/animations.js

@@ -0,0 +1,124 @@
+/**
+ * Fast-forwarded animations on the host side (PLAN-1.6 F4, AGENT-TOOLS 1.13 18.12). The app does the work (its
+ * `animations` command and its three layers); the host remembers which sessions it switched on, so that it can
+ * put them back for a measurement and when the session ends. State is kept per host, not per tools object, because
+ * several agents' tools share one app.
+ */
+/** The line every answer carries while fast animations are on (the shape of the network line). */
+export const ANIMATIONS_LINE = "Animations: fast (Tapline).";
+/** What a call says when it could not be run with animations normal. */
+export const ANIMATIONS_NOT_PAUSED_NOTE = "Note: animations could not be set to normal for this call; it ran with fast animations.";
+/** What a call that ran with animations paused says at its end. */
+export const ANIMATIONS_PAUSED_NOTE = "Note: animations were normal during this call.";
+const on = new WeakMap();
+const pauses = new WeakMap();
+function pausesOf(host) {
+    const known = pauses.get(host);
+    if (known !== undefined)
+        return known;
+    const made = new Map();
+    pauses.set(host, made);
+    return made;
+}
+function setOf(map, host) {
+    const known = map.get(host);
+    if (known !== undefined)
+        return known;
+    const made = new Set();
+    map.set(host, made);
+    return made;
+}
+/** Whether the host switched fast animations on for this session and they are meant to be on. */
+export function animationsOn(host, sessionId) {
+    return setOf(on, host).has(sessionId);
+}
+/** Records what the app's `animations` command was last set to. */
+export function noteAnimations(host, sessionId, speed) {
+    const sessions = setOf(on, host);
+    if (speed === "fast")
+        sessions.add(sessionId);
+    else
+        sessions.delete(sessionId);
+}
+/** Waits while a measurement holds the session at normal: an explicit switch to fast must not land inside it. */
+export async function afterPause(host, sessionId) {
+    for (let pause = pausesOf(host).get(sessionId); pause !== undefined; pause = pausesOf(host).get(sessionId))
+        await pause.over;
+}
+async function send(host, sessionId, speed) {
+    try {
+        await host.request("command", { name: "animations", args: { speed } }, { sessionId });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Runs `run` with animations normal when they are on for the session, and puts them back after, whatever `run` does.
+ * `paused` is true when they were on and are normal for this call; `failed` when the switch to normal did not go through
+ * (the call then ran fast, and says so). Pauses overlapping in one session are counted: normal is sent by the first and
+ * fast comes back when the last one ends.
+ */
+export async function withNormalAnimations(host, sessionId, run) {
+    if (sessionId === undefined || !animationsOn(host, sessionId))
+        return { value: await run(), paused: false, failed: false };
+    const all = pausesOf(host);
+    let pause = all.get(sessionId);
+    if (pause === undefined) {
+        let end = () => undefined;
+        const over = new Promise((resolve) => (end = resolve));
+        pause = { count: 0, ready: send(host, sessionId, "normal"), over, end };
+        all.set(sessionId, pause);
+    }
+    pause.count += 1;
+    const mine = pause;
+    const accepted = await mine.ready;
+    try {
+        return { value: await run(), paused: accepted, failed: !accepted };
+    }
+    finally {
+        mine.count -= 1;
+        if (mine.count === 0) {
+            if (all.get(sessionId) === mine)
+                all.delete(sessionId);
+            // A switch made during the call wins: only put fast back when it is still meant to be on.
+            try {
+                if (animationsOn(host, sessionId))
+                    await send(host, sessionId, "fast");
+            }
+            finally {
+                mine.end();
+            }
+        }
+    }
+}
+/**
+ * Puts one session back to normal for good (a journey in a user's eyes starts). False when they were not on, or when
+ * the app refused the switch: the session then stays tracked as fast, so nothing reports animations as normal.
+ */
+export async function endAnimations(host, sessionId) {
+    const sessions = setOf(on, host);
+    if (!sessions.has(sessionId))
+        return false;
+    if (!(await send(host, sessionId, "normal")))
+        return false;
+    sessions.delete(sessionId);
+    return true;
+}
+/** The session ends: every session this host switched to fast goes back to normal. A session that is gone is skipped. */
+export async function restoreAnimations(host) {
+    const sessions = setOf(on, host);
+    const ids = [...sessions];
+    // A session the app would not put back stays tracked as fast.
+    await Promise.all(ids.map(async (id) => {
+        if (await send(host, id, "normal"))
+            sessions.delete(id);
+    }));
+}
+/** Forgets a session that ended (the app restores itself on a disconnect). */
+export function forgetAnimations(host, sessionId) {
+    setOf(on, host).delete(sessionId);
+    pausesOf(host).delete(sessionId);
+}
+//# sourceMappingURL=animations.js.map

package/dist/animations.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"animations.js","sourceRoot":"","sources":["../src/animations.ts"],"names":[],"mappings":"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"}

package/dist/api.d.ts

@@ -0,0 +1,43 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+/**
+ * `POST /api/<tool>` (AGENT-TOOLS 1.13 §18.10): the thin call's way in. Only a standalone `tapline host` sets an
+ * `api` handler; a host inside an agent's MCP server has none and answers 404, so one agent's session can't be
+ * driven by another's thin calls. The handler returns undefined for a tool that doesn't exist.
+ */
+export type ApiHandler = (tool: string, args: Record<string, unknown>, clientId: string | undefined, 
+/** Aborts when the client disconnects before the answer: queued work that nobody waits for is skipped. */
+signal: AbortSignal) => Promise<CallToolResult | undefined>;
+/** The most a call's JSON may be. */
+export declare const MAX_API_BODY: number;
+export declare function safeEqual(a: string, b: string): boolean;
+/** An address as one spelling: no brackets, lower case, and an IPv4-mapped IPv6 address as plain IPv4. */
+export declare function normalizeAddress(address: string): string;
+/**
+ * The host's proof that it holds the token: an HMAC of the caller's fresh challenge and of the address and port the request
+ * arrived on, keyed by the token. They are in it so that a listener on another port, or on another address with the same
+ * port (::1 against 127.0.0.1), can't relay the probe to the real host and hand its proof back: a proof made for one
+ * endpoint never verifies for another. The token itself never leaves; thincall.ts computes the same value from the socket
+ * it connected to and sends the token only to a host that proves it for that endpoint.
+ */
+export declare function hostProof(token: string, challenge: string, address: string, port: number): string;
+/** What goes back as JSON: the answer's text, whether it is a refusal, and the first picture when there is one. */
+export interface ApiAnswer {
+    text: string;
+    isError: boolean;
+    image?: {
+        mimeType: string;
+        dataBase64: string;
+    };
+}
+export declare function toApiAnswer(result: CallToolResult): ApiAnswer;
+export interface ApiRequestContext {
+    /** The host's token; never written into an answer. */
+    token: string;
+    /** Whether the peer is this computer. */
+    loopback: boolean;
+    /** Undefined on a host that doesn't serve the thin call. */
+    handler: ApiHandler | undefined;
+}
+/** Answers `/api/<tool>`; false for any other path. Checks run in the order this computer, method, token. */
+export declare function handleApi(req: IncomingMessage, res: ServerResponse, context: ApiRequestContext): boolean;