@ykurilov/agent-chat-web-tools 0.0.0-stage → 0.56.0

package/dist/labels.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/labels.ts"],"sourcesContent":["/** Подписи веб-инструментов в ленте чата. Без кода сервисов: файл безопасно подключать в браузерной сборке. */\nexport const webToolTitles: Record<string, string> = {\n  web_search: \"Поиск в интернете\",\n  read_page: \"Чтение страницы\",\n  page_screenshot: \"Скриншот страницы\",\n};\n\n/** Те же подписи по-английски. */\nexport const englishWebToolTitles: Record<string, string> = {\n  web_search: \"Web search\",\n  read_page: \"Reading a page\",\n  page_screenshot: \"Page screenshot\",\n};\n\n/** Понятные фразы веб-инструментов для простого вида чата (`stepPhrases` у `AgentChat`): «идёт» и «готово». */\nexport const webToolStepPhrases: Record<string, { running: string; done: string }> = {\n  web_search: { running: \"Ищу в интернете\", done: \"Поискал в интернете\" },\n  read_page: { running: \"Читаю страницу\", done: \"Прочитал страницу\" },\n  page_screenshot: { running: \"Делаю снимок страницы\", done: \"Сделал снимок страницы\" },\n};\n\n/** Те же фразы по-английски. */\nexport const englishWebToolStepPhrases: Record<string, { running: string; done: string }> = {\n  web_search: { running: \"Searching the web\", done: \"Searched the web\" },\n  read_page: { running: \"Reading a page\", done: \"Read a page\" },\n  page_screenshot: { running: \"Taking a page screenshot\", done: \"Took a page screenshot\" },\n};\n\ninterface ToolLabels {\n  toolRunning(toolName: string): string;\n  toolDone(toolName: string): string;\n  toolError(toolName: string): string;\n}\n\nfunction titleOf(titles: Record<string, string>, toolName: string): string {\n  return Object.hasOwn(titles, toolName) ? (titles[toolName] ?? toolName) : toolName;\n}\n\n/** Надписи чата, в которых веб-инструменты названы по-русски (или по словарю `titles`, например `englishWebToolTitles`); остальное не меняется. */\nexport function withWebToolTitles<Labels extends ToolLabels>(labels: Labels, titles: Record<string, string> = webToolTitles): Labels {\n  return {\n    ...labels,\n    toolRunning: (toolName: string) => labels.toolRunning(titleOf(titles, toolName)),\n    toolDone: (toolName: string) => labels.toolDone(titleOf(titles, toolName)),\n    toolError: (toolName: string) => labels.toolError(titleOf(titles, toolName)),\n  };\n}\n"],"mappings":";AACO,IAAM,gBAAwC;AAAA,EACnD,YAAY;AAAA,EACZ,WAAW;AAAA,EACX,iBAAiB;AACnB;AAGO,IAAM,uBAA+C;AAAA,EAC1D,YAAY;AAAA,EACZ,WAAW;AAAA,EACX,iBAAiB;AACnB;AAGO,IAAM,qBAAwE;AAAA,EACnF,YAAY,EAAE,SAAS,oFAAmB,MAAM,2GAAsB;AAAA,EACtE,WAAW,EAAE,SAAS,mFAAkB,MAAM,oGAAoB;AAAA,EAClE,iBAAiB,EAAE,SAAS,wHAAyB,MAAM,6HAAyB;AACtF;AAGO,IAAM,4BAA+E;AAAA,EAC1F,YAAY,EAAE,SAAS,qBAAqB,MAAM,mBAAmB;AAAA,EACrE,WAAW,EAAE,SAAS,kBAAkB,MAAM,cAAc;AAAA,EAC5D,iBAAiB,EAAE,SAAS,4BAA4B,MAAM,yBAAyB;AACzF;AAQA,SAAS,QAAQ,QAAgC,UAA0B;AACzE,SAAO,OAAO,OAAO,QAAQ,QAAQ,IAAK,OAAO,QAAQ,KAAK,WAAY;AAC5E;AAGO,SAAS,kBAA6C,QAAgB,SAAiC,eAAuB;AACnI,SAAO;AAAA,IACL,GAAG;AAAA,IACH,aAAa,CAAC,aAAqB,OAAO,YAAY,QAAQ,QAAQ,QAAQ,CAAC;AAAA,IAC/E,UAAU,CAAC,aAAqB,OAAO,SAAS,QAAQ,QAAQ,QAAQ,CAAC;AAAA,IACzE,WAAW,CAAC,aAAqB,OAAO,UAAU,QAAQ,QAAQ,QAAQ,CAAC;AAAA,EAC7E;AACF;","names":[]}

package/dist/types/create-web-tools.d.ts

@@ -0,0 +1,55 @@
+import type { ToolSet } from "ai";
+import type { ChatStorage } from "@ykurilov/agent-chat-core";
+import type { HostResolver } from "./page-address.js";
+import type { PageReaderService, PageScreenshotService, WebSearchService } from "./services.js";
+export interface CreateWebToolsOptions {
+    search: WebSearchService;
+    reader: PageReaderService;
+    /** Сколько результатов возвращает поиск. */
+    searchResultLimit?: number;
+    /** Сколько знаков страницы отдаётся модели. */
+    pageCharacterLimit?: number;
+    /** Служба снимков. Без неё инструмента `page_screenshot` нет. */
+    screenshots?: PageScreenshotService;
+    /** Для скачивания снимка при сборке запроса к модели. */
+    fetch?: typeof globalThis.fetch;
+    /** Как разрешать имена при скачивании снимка. По умолчанию системный DNS; заменяется в тестах. */
+    resolveHost?: HostResolver;
+    /**
+     * Траты служб в лимит расходов: удачный вызов и вызов, оборванный после отправки запроса, пишутся расходом `web_tools`.
+     * Без него вызовы не учитываются.
+     */
+    spending?: WebToolsSpending;
+}
+/** Учёт трат веб-служб: запись идёт в то же хранилище, по которому считает лимит расходов. */
+export interface WebToolsSpending {
+    storage: Pick<ChatStorage, "insertUsageRecord">;
+    /**
+     * Доллары за один удачный вызов. У Firecrawl поиск стоит 2 кредита за 10 результатов, страница и снимок — 1 кредит;
+     * цена кредита — по вашему тарифу. Инструмент без цены не учитывается.
+     */
+    pricePerCallUsd: {
+        web_search: number;
+        read_page: number;
+        page_screenshot?: number;
+    };
+    /** Служба в записи расхода; по умолчанию `firecrawl`. */
+    providerId?: string;
+    logError?: (message: string) => void;
+    now?: () => number;
+}
+/** Выбранная модель: то, что ядро передаёт функции-набору инструментов. */
+export interface WebToolsModel {
+    /** `toolResultImageProviders` — профиль модели: через каких провайдеров она видит картинку в результате инструмента. */
+    profile: {
+        acceptsImages: boolean;
+        acceptsImagesByProvider?: Readonly<Record<string, boolean>>;
+        toolResultImageProviders?: readonly string[];
+    };
+    providerId: string;
+    /** Чей ход и в каком чате: на них пишется расход (`spending`). Ядро передаёт их само. */
+    ownerId?: string;
+    chatId?: string;
+}
+/** Набор веб-инструментов для `agent.tools` ядра: `tools: (model) => ({ ...appTools, ...webTools(model) })`. */
+export declare function createWebTools(options: CreateWebToolsOptions): (model: WebToolsModel) => ToolSet;

package/dist/types/dns-host-resolver.d.ts

@@ -0,0 +1,3 @@
+import type { HostResolver } from "./page-address.js";
+/** Все адреса имени по системному DNS. */
+export declare const dnsHostResolver: HostResolver;

package/dist/types/firecrawl/firecrawl-services.d.ts

@@ -0,0 +1,17 @@
+import type { PageReaderService, PageScreenshotService, WebSearchService } from "../services.js";
+export interface FirecrawlOptions {
+    apiKey: string;
+    /** Адрес сервиса или прокси перед ним; по умолчанию https://api.firecrawl.dev. */
+    baseUrl?: string;
+    /** Дополнительные заголовки каждого запроса, например токен прокси. */
+    headers?: Record<string, string>;
+    fetch?: typeof globalThis.fetch;
+    /** Предел ожидания ответа, мс. По умолчанию 30 000 для поиска и 60 000 для чтения и снимка. */
+    timeoutMs?: number;
+}
+export interface FirecrawlServices {
+    search: WebSearchService;
+    reader: PageReaderService;
+    screenshots: PageScreenshotService;
+}
+export declare function createFirecrawlServices(options: FirecrawlOptions): FirecrawlServices;

package/dist/types/image-cache.d.ts

@@ -0,0 +1,13 @@
+import type { DownloadedImage } from "./screenshot-download.js";
+export interface ImageCacheOptions {
+    maxEntries: number;
+    maxBytes: number;
+    ttlMs: number;
+    now?: () => number;
+}
+export interface ImageCache {
+    get(key: string): DownloadedImage | undefined;
+    set(key: string, image: DownloadedImage): void;
+}
+/** Кэш картинок в памяти: ограничен числом, общим объёмом и временем жизни; первой уходит давно не нужная запись. */
+export declare function createImageCache({ maxEntries, maxBytes, ttlMs, now }: ImageCacheOptions): ImageCache;

package/dist/types/index.d.ts

@@ -0,0 +1,11 @@
+export { createWebTools } from "./create-web-tools.js";
+export type { CreateWebToolsOptions, WebToolsModel, WebToolsSpending } from "./create-web-tools.js";
+export { createPersonLinkTool, PERSON_LINK_TOOL, PERSON_LINKS_PER_CHAT } from "./tools/person-link-view.js";
+export type { PersonLinkModel, PersonLinkOptions, PersonLinkTools } from "./tools/person-link-view.js";
+export { webToolsInstructions } from "./instructions.js";
+export { assertPublicWebAddress, assertResolvesPublic, isHttpAddress, isPrivateAddress } from "./page-address.js";
+export type { HostResolver } from "./page-address.js";
+export { dnsHostResolver } from "./dns-host-resolver.js";
+export { WebToolError } from "./web-tool-error.js";
+export type { WebToolErrorKind } from "./web-tool-error.js";
+export type { PageContent, PageReaderService, PageScreenshotService, SearchHit, WebSearchService } from "./services.js";

package/dist/types/instructions.d.ts

@@ -0,0 +1,2 @@
+/** Дополнение к инструкции агента: как пользоваться веб-инструментами. Текст постоянный (кэш модели). */
+export declare const webToolsInstructions: string;

package/dist/types/labels.d.ts

@@ -0,0 +1,22 @@
+/** Подписи веб-инструментов в ленте чата. Без кода сервисов: файл безопасно подключать в браузерной сборке. */
+export declare const webToolTitles: Record<string, string>;
+/** Те же подписи по-английски. */
+export declare const englishWebToolTitles: Record<string, string>;
+/** Понятные фразы веб-инструментов для простого вида чата (`stepPhrases` у `AgentChat`): «идёт» и «готово». */
+export declare const webToolStepPhrases: Record<string, {
+    running: string;
+    done: string;
+}>;
+/** Те же фразы по-английски. */
+export declare const englishWebToolStepPhrases: Record<string, {
+    running: string;
+    done: string;
+}>;
+interface ToolLabels {
+    toolRunning(toolName: string): string;
+    toolDone(toolName: string): string;
+    toolError(toolName: string): string;
+}
+/** Надписи чата, в которых веб-инструменты названы по-русски (или по словарю `titles`, например `englishWebToolTitles`); остальное не меняется. */
+export declare function withWebToolTitles<Labels extends ToolLabels>(labels: Labels, titles?: Record<string, string>): Labels;
+export {};

package/dist/types/page-address.d.ts

@@ -0,0 +1,14 @@
+/** Определяет адреса имени. В приложении это DNS; в тестах подменяется. */
+export type HostResolver = (hostname: string) => Promise<string[]>;
+/** Адрес http или https: единственные схемы, которые пускают в результаты и в скачивание. */
+export declare function isHttpAddress(address: string): boolean;
+/** Пропускает только публичные адреса http и https: сервис чтения не должен ходить во внутреннюю сеть. */
+export declare function assertPublicWebAddress(address: string): URL;
+/**
+ * Проверка по DNS для тех, кто ходит по адресу сам: имя разрешается, и если хоть один адрес частный
+ * (или имя не разрешилось), оно отклоняется. Адрес-число уже проверен `assertPublicWebAddress`.
+ * Между проверкой и запросом остаётся короткое окно: fetch разрешает имя ещё раз.
+ */
+export declare function assertResolvesPublic(url: URL, resolveHost: HostResolver): Promise<void>;
+/** Адрес из ответа DNS (без скобок). Всё, что не удалось разобрать, считается частным. */
+export declare function isPrivateAddress(address: string): boolean;

package/dist/types/result-text.d.ts

@@ -0,0 +1,5 @@
+import type { PageContent, SearchHit } from "./services.js";
+/** Результат поиска: нумерованный список, заголовок ссылкой, ниже выдержка. Один текст для модели и для человека. */
+export declare function formatSearchResults(query: string, hits: SearchHit[]): string;
+/** Страница: заголовок, источник и текст; длинный текст режется на границе абзаца с пометкой. */
+export declare function formatPage(page: PageContent, characterLimit: number): string;

package/dist/types/screenshot-download.d.ts

@@ -0,0 +1,19 @@
+import type { HostResolver } from "./page-address.js";
+export declare const screenshotDownloadTimeoutMs = 20000;
+export declare const screenshotMaxBytes: number;
+export interface DownloadedImage {
+    bytes: Uint8Array;
+    mediaType: string;
+}
+export declare const screenshotMaxRedirects = 3;
+export interface ScreenshotDownloadOptions {
+    /** Разрешает имя в адреса для проверки: наш сервер сам ходит по этому адресу. */
+    resolveHost: HostResolver;
+}
+/**
+ * Скачивает снимок по адресу из записи истории. Возвращает `undefined`, если снимка больше нет:
+ * ссылка устарела, это не картинка, она слишком велика или ведёт не туда. Переходы выполняются вручную,
+ * не больше трёх, и каждый проходит ту же проверку, что и первый адрес: только http(s), не локальный адрес,
+ * имя не указывает во внутреннюю сеть.
+ */
+export declare function downloadScreenshot(address: string, fetchImplementation: typeof globalThis.fetch, { resolveHost }: ScreenshotDownloadOptions): Promise<DownloadedImage | undefined>;

package/dist/types/service-call.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Вызов сервиса из инструмента. Ошибки своей реализации сервиса (не `WebToolError`) наружу не идут:
+ * в их тексте могут оказаться ключ или адрес. Остановка хода проходит как есть.
+ */
+export declare function callService<Result>(signal: AbortSignal | undefined, call: () => Promise<Result>): Promise<Result>;

package/dist/types/services.d.ts

@@ -0,0 +1,29 @@
+/** Что нужно инструментам от сервисов. Реализация заменяется без правки инструментов (Firecrawl, Exa и другие). */
+export interface SearchHit {
+    title: string;
+    url: string;
+    snippet: string;
+}
+export interface WebSearchService {
+    search(query: string, options: {
+        limit: number;
+        signal?: AbortSignal;
+    }): Promise<SearchHit[]>;
+}
+export interface PageContent {
+    url: string;
+    title: string;
+    markdown: string;
+}
+export interface PageReaderService {
+    readPage(url: string, options: {
+        signal?: AbortSignal;
+    }): Promise<PageContent>;
+}
+export interface PageScreenshotService {
+    takeScreenshot(url: string, options: {
+        signal?: AbortSignal;
+    }): Promise<{
+        imageUrl: string;
+    }>;
+}

package/dist/types/tools/page-screenshot.d.ts

@@ -0,0 +1,15 @@
+import type { Tool } from "ai";
+import type { HostResolver } from "../page-address.js";
+import type { PageScreenshotService } from "../services.js";
+export interface ScreenshotRecord {
+    pageUrl: string;
+    screenshotUrl: string;
+}
+/**
+ * В историю попадают только два адреса (запись маленькая). Картинку модель получает при сборке каждого запроса:
+ * снимок скачивается заново, а если ссылка устарела, вместо картинки уходит текст.
+ * Описание и схема неизменны при любых настройках и службах: от них зависит кэш модели.
+ */
+export declare function pageScreenshotTool(screenshots: PageScreenshotService, fetchImplementation: typeof globalThis.fetch, resolveHost: HostResolver): Tool<{
+    url: string;
+}, ScreenshotRecord>;

package/dist/types/tools/person-link-view.d.ts

@@ -0,0 +1,41 @@
+import type { ChatStorage } from "@ykurilov/agent-chat-core";
+import type { ToolSet } from "ai";
+import type { WebToolsModel } from "../create-web-tools.js";
+import type { HostResolver } from "../page-address.js";
+import type { PageReaderService, PageScreenshotService } from "../services.js";
+/** Имя инструмента: его же ждёт правило сценария (`flows/prompt/rules/link-views.ts`). */
+export declare const PERSON_LINK_TOOL = "person_link_view";
+/** Сколько раз за разговор агент смотрит ссылки человека. */
+export declare const PERSON_LINKS_PER_CHAT = 3;
+export interface PersonLinkOptions {
+    /** Для чтения слов человека и счёта просмотров; в него же пишется расход `web_tools`. */
+    storage: Pick<ChatStorage, "listMessages" | "listBranchSelections" | "insertUsageRecord">;
+    /** Снимок страницы: его видят модели, которым провайдер отдаёт картинку в результате инструмента. */
+    screenshots?: PageScreenshotService;
+    /** Текст страницы: для моделей без картинок. Нет ни службы снимков для модели, ни чтения — инструмента нет. */
+    reader?: PageReaderService;
+    /** Сколько просмотров за разговор; по умолчанию три. */
+    maxPerChat?: number;
+    /** Домены приложений: голое имя от человека («sveta-nails») открывается на них («sveta-nails.ykapp.ru»). */
+    appDomains?: readonly string[];
+    /** Доллары за один просмотр (кредит службы); пишется расходом `web_tools`. */
+    pricePerViewUsd?: number;
+    fetch?: typeof globalThis.fetch;
+    resolveHost?: HostResolver;
+    logError?: (message: string) => void;
+}
+/** Ход, для которого собирается набор: чат обязателен, `turnId` отделяет вызовы идущего хода. */
+export type PersonLinkModel = WebToolsModel & {
+    turnId?: string;
+};
+/** Набор для `agent.tools`: `{ person_link_view }` или пустой. `appDomains` вызова дополняют настройку. */
+export type PersonLinkTools = (model: PersonLinkModel, call?: {
+    appDomains?: readonly string[];
+}) => ToolSet;
+/**
+ * Инструмент «посмотреть ссылку собеседника»: только адрес из реплик человека (или короткое имя на домене приложений),
+ * не больше `maxPerChat` просмотров за разговор. Описание и схема одни для всех моделей: от них зависит кэш.
+ */
+export declare function createPersonLinkTool(options: PersonLinkOptions): PersonLinkTools;
+/** Один вид для сравнения: без протокола, «www», хвостовой косой черты, якоря и знаков препинания в конце. */
+export declare function normalizeAddress(raw: string): string;

package/dist/types/tools/read-page.d.ts

@@ -0,0 +1,6 @@
+import type { Tool } from "ai";
+import type { PageReaderService } from "../services.js";
+/** Описание и схема неизменны при любых настройках и службах: от них зависит кэш модели. */
+export declare function readPageTool(reader: PageReaderService, characterLimit: number): Tool<{
+    url: string;
+}, string>;

package/dist/types/tools/web-search.d.ts

@@ -0,0 +1,6 @@
+import type { Tool } from "ai";
+import type { WebSearchService } from "../services.js";
+/** Описание и схема неизменны при любых настройках и службах: от них зависит кэш модели. */
+export declare function webSearchTool(search: WebSearchService, resultLimit: number): Tool<{
+    query: string;
+}, string>;

package/dist/types/web-tool-error.d.ts

@@ -0,0 +1,18 @@
+export type WebToolErrorKind = "bad_address" | "bad_query" | "invalid_key" | "insufficient_funds" | "rate_limited" | "unavailable" | "timeout" | "bad_response";
+/**
+ * Ошибка веб-инструмента. Текст по-русски показывается и модели, и человеку в строке вызова,
+ * поэтому в нём нет ключа, адреса сервиса и заголовков.
+ */
+export declare class WebToolError extends Error {
+    readonly kind: WebToolErrorKind;
+    constructor(kind: WebToolErrorKind, message: string);
+}
+export declare const serviceFailureMessages: {
+    readonly invalid_key: "Сервис веб-инструментов отклонил ключ доступа.";
+    readonly insufficient_funds: "На счёте сервиса веб-инструментов закончились средства.";
+    readonly rate_limited: "Превышен лимит запросов сервиса веб-инструментов, попробуйте позже.";
+    readonly unavailable: "Сервис веб-инструментов сейчас недоступен, попробуйте позже.";
+    readonly timeout: "Сервис веб-инструментов не ответил вовремя.";
+    readonly bad_response: "Сервис веб-инструментов вернул неожиданный ответ.";
+};
+export declare function serviceFailure(kind: keyof typeof serviceFailureMessages): WebToolError;

package/package.json

@@ -1,6 +1,50 @@
 {
   "name": "@ykurilov/agent-chat-web-tools",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.56.0",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "exports": {
+    ".": {
+      "@ykurilov/agent-chat-source": "./src/index.ts",
+      "types": "./dist/types/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./firecrawl": {
+      "@ykurilov/agent-chat-source": "./src/firecrawl/firecrawl-services.ts",
+      "types": "./dist/types/firecrawl/firecrawl-services.d.ts",
+      "import": "./dist/firecrawl.js"
+    },
+    "./labels": {
+      "@ykurilov/agent-chat-source": "./src/labels.ts",
+      "types": "./dist/types/labels.d.ts",
+      "import": "./dist/labels.js"
+    }
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ykurilov/agent-chat-sdk.git",
+    "directory": "packages/web-tools"
+  },
+  "dependencies": {
+    "ai": "7.0.122",
+    "zod": "^4.6.5",
+    "@ykurilov/agent-chat-core": "0.56.0"
+  },
+  "scripts": {
+    "build": "node ../../scripts/build-package.mjs",
+    "typecheck": "tsc -p tsconfig.json"
+  }
 }