charness 0.0.0-stage → 3.1.0

package/dist/utils/fileSendPlan.d.ts

@@ -0,0 +1,217 @@
+/**
+ * @description Pure decision layer for the agent→Telegram file/image send
+ * (`send_file_to_user` MCP tool). Four concerns, all side-effect-free enough to
+ * unit-test without booting Telegraf:
+ *   1. {@link resolveSendFileWithinDir} — path-safety: resolve a caller-supplied
+ *      path against the topic's bound folder and confirm (realpath + containment)
+ *      it points at a REGULAR FILE inside it. Modeled on
+ *      `validation.ts:validateSubdir`, but for a file (not a directory) and
+ *      returning a discriminated result instead of throwing (the caller surfaces
+ *      the error to the agent as an MCP tool error).
+ *   2. {@link classifyFileSendKind} — map an extension to how Telegram should
+ *      render it (inline photo / autoplay animation / inline video / plain document).
+ *   3. {@link planFileSend} — decide the single Telegram send method (or album
+ *      shape) for 1..10 items, applying the `as_file` override, the photo size
+ *      downgrade, and the album photo/video-vs-document rule. Returns the
+ *      over-cap / count violations as an error variant rather than throwing.
+ *   4. {@link buildTelegramFileSendRequest} — turn a non-error plan into the
+ *      exact typed Bot API request shape, including caption placement.
+ *
+ * The only fs touch is the bigint `statSync` inside
+ * {@link resolveSendFileWithinDir} (unavoidable for the regular-file and
+ * identity gates). The caller supplies owned descriptor snapshots, so planning
+ * and request construction never carry workspace paths into Telegraf.
+ */
+/** Telegram's inline-photo size cap; a photo-eligible file over this downgrades to a document. */
+export declare const telegramPhotoMaxBytes: number;
+/** Bot API hard send cap per file; anything over this is rejected, never sent. */
+export declare const telegramSendMaxBytes: number;
+/** Minimum item count that forms a media-group album (below ⇒ single send). */
+export declare const mediaGroupMin = 2;
+/** Maximum item count Telegram accepts in one media-group album. */
+export declare const mediaGroupMax = 10;
+/** Telegram caption length cap (characters); longer captions are trimmed. */
+export declare const captionMaxLength = 1024;
+/** Extensions rendered as inline photos (lowercased, leading dot). */
+export declare const photoExtensions: readonly string[];
+/** Extensions rendered as looping animations (lowercased, leading dot). */
+export declare const animationExtensions: readonly string[];
+/** Extensions rendered with Telegram's native streaming video player. */
+export declare const videoExtensions: readonly string[];
+/**
+ * @name FileSendKind
+ * @description How Telegram should render a file: inline `photo`, autoplay
+ * `animation` (gif), native `video`, or plain `document`.
+ */
+export type FileSendKind = 'photo' | 'animation' | 'video' | 'document';
+/**
+ * @name ResolveSendFileCode
+ * @description Stable failure code for {@link resolveSendFileWithinDir}, so the
+ * caller can build a readable, path-naming tool error per case.
+ */
+export type ResolveSendFileCode = 'INVALID_CHARS' | 'OUTSIDE_FOLDER' | 'NOT_FOUND' | 'NOT_A_FILE';
+/** Device/inode identity captured during canonical-path validation. */
+export interface FileIdentity {
+    dev: bigint;
+    ino: bigint;
+}
+/**
+ * @name ResolveSendFileResult
+ * @description Discriminated outcome of resolving a single send path. `ok` carries
+ * the safe absolute path, its canonical root, and file identity; the failure
+ * carries a readable message + a stable code.
+ */
+export type ResolveSendFileResult = {
+    ok: true;
+    absPath: string;
+    rootPath: string;
+    identity: FileIdentity;
+} | {
+    ok: false;
+    error: string;
+    code: ResolveSendFileCode;
+};
+/**
+ * @description Resolve `rawPath` against the topic's bound `workDir` and confirm
+ * it points at a regular file living inside it. A multi-file caller supplies
+ * `pinnedRootPath` after the first item so a replaced binding cannot become a
+ * new trusted root between album items. Defence-in-depth mirrors
+ * `validateSubdir`: reject control chars, NFC-normalise, canonicalize the root,
+ * then use the shared canonical candidate containment gate. The final gate differs: this is for a
+ * FILE, so `statSync` must report a regular file (a directory or socket is
+ * rejected, not accepted).
+ */
+export declare function resolveSendFileWithinDir(workDir: string, rawPath: string, pinnedRootPath?: string): ResolveSendFileResult;
+/**
+ * @description Classify a path by its lowercased extension into the Telegram
+ * render kind. `.png/.jpg/.jpeg/.webp` → photo; `.gif` → animation; `.mp4` →
+ * video; anything else → document.
+ */
+export declare function classifyFileSendKind(filePath: string): FileSendKind;
+/** Derive a multipart-safe filename from a canonical file path. */
+export declare function getTelegramUploadFilename(filePath: string): string;
+/**
+ * @description Trim a caption to Telegram's {@link captionMaxLength} cap. Returns
+ * `undefined` for an absent/blank caption so callers can omit the field entirely.
+ */
+export declare function trimCaption(caption: string | undefined): string | undefined;
+/**
+ * @name FileSendItem
+ * @description One resolved file the planner reasons about: its safe absolute
+ * path, pinned descriptor snapshot, and render kind.
+ */
+export interface FileSendItem {
+    absPath: string;
+    source: FileDescriptorSnapshot;
+    kind: FileSendKind;
+}
+/**
+ * @name FileSendPlan
+ * @description Discriminated send plan:
+ *  - `kind: 'send'` — one file via a single Telegram method (`mode`).
+ *  - `kind: 'album'` — 2..10 files via `sendMediaGroup`, either native photos /
+ *    videos or all documents (`mode`).
+ *  - `kind: 'error'` — a count/size violation; `error` names the offending file.
+ */
+export type FileSendPlan = {
+    kind: 'send';
+    mode: FileSendKind;
+    item: FileSendItem;
+} | {
+    kind: 'album';
+    mode: 'albumPhotoVideo' | 'albumDocument';
+    items: FileSendItem[];
+} | {
+    kind: 'error';
+    error: string;
+};
+/** A validated plan that can be converted into a Telegram request. */
+export type NonErrorFileSendPlan = Exclude<FileSendPlan, {
+    kind: 'error';
+    error: string;
+}>;
+/** Exact Bot API methods used for one-file sends. */
+export type TelegramSingleFileSendMethod = 'sendPhoto' | 'sendAnimation' | 'sendVideo' | 'sendDocument';
+/** Owned descriptor snapshot transferred from the reader to the send service. */
+export interface FileDescriptorSnapshot {
+    fd: number;
+    filename: string;
+    sizeBytes: number;
+}
+export interface FileSendPhotoMedia {
+    type: 'photo';
+    media: FileDescriptorSnapshot;
+    caption?: string;
+}
+export interface FileSendVideoMedia {
+    type: 'video';
+    media: FileDescriptorSnapshot;
+    caption?: string;
+}
+export interface FileSendDocumentMedia {
+    type: 'document';
+    media: FileDescriptorSnapshot;
+    caption?: string;
+}
+/** Native photo/video group accepted by the file-send gateway. */
+export interface FileSendPhotoVideoMediaGroup {
+    kind: 'photoVideo';
+    media: Array<FileSendPhotoMedia | FileSendVideoMedia>;
+}
+/** Homogeneous document group accepted by the file-send gateway. */
+export interface FileSendDocumentMediaGroup {
+    kind: 'document';
+    media: FileSendDocumentMedia[];
+}
+/** Project-owned media group; the discriminant preserves Bot API homogeneity. */
+export type FileSendMediaGroup = FileSendPhotoVideoMediaGroup | FileSendDocumentMediaGroup;
+/** One-file request ready for `bot.telegram[method]`, apart from thread routing. */
+export interface TelegramSingleFileSendRequest {
+    method: TelegramSingleFileSendMethod;
+    source: FileDescriptorSnapshot;
+    caption?: string;
+}
+/** Photo/video media-group request preserving each eligible item's native type. */
+export interface TelegramPhotoVideoAlbumRequest {
+    method: 'sendMediaGroup';
+    mediaGroup: FileSendPhotoVideoMediaGroup;
+}
+/** Document media-group request used for every whole-album fallback. */
+export interface TelegramDocumentAlbumRequest {
+    method: 'sendMediaGroup';
+    mediaGroup: FileSendDocumentMediaGroup;
+}
+/** Exact Telegram request built from a non-error file-send plan. */
+export type TelegramFileSendRequest = TelegramSingleFileSendRequest | TelegramPhotoVideoAlbumRequest | TelegramDocumentAlbumRequest;
+/**
+ * @description Convert a non-error plan into the exact Telegram request the bot
+ * executes. Captions are trimmed here and included on a single request or only
+ * the first media-group entry. `albumPhotoVideo` accepts only photo/video items;
+ * an impossible hand-built plan throws a path-naming error instead of silently
+ * sending another kind as a photo.
+ */
+export declare function buildTelegramFileSendRequest(plan: NonErrorFileSendPlan, caption?: string): TelegramFileSendRequest;
+/** Existing user-facing hard-cap error shared by planning and snapshot reads. */
+export declare function getTelegramFileOversizeError(absPath: string): string;
+/** Existing user-facing item-count validation shared by planning and the reader. */
+export declare function getFileSendCountError(itemCount: number): string | null;
+/**
+ * @description Decide how to deliver 1..10 resolved files.
+ *
+ * Single file: the method is the item's kind, with two overrides —
+ *  - `asFile` forces `document` for every kind, and
+ *  - a photo over {@link telegramPhotoMaxBytes} downgrades to `document` so it
+ *    still goes through (just not inline).
+ *
+ * Album (2..10): `albumPhotoVideo` when `!asFile` and EVERY item is either a
+ * video or a photo within the photo cap, preserving each item's native media
+ * type in all-photo, all-video, and mixed photo/video groups. Otherwise use
+ * `albumDocument` (animations/documents and over-cap photos included — a media
+ * group cannot carry animation items, so a gif rides as a document in an album
+ * and only autoplays when sent alone).
+ *
+ * Returns an `error` plan for 0 items, >{@link mediaGroupMax}, or any item over
+ * {@link telegramSendMaxBytes}.
+ */
+export declare function planFileSend(items: FileSendItem[], asFile: boolean): FileSendPlan;
+//# sourceMappingURL=fileSendPlan.d.ts.map

package/dist/utils/fileSendPlan.d.ts.map

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

package/dist/utils/fileSendPlan.js

@@ -0,0 +1,291 @@
+"use strict";
+/**
+ * @description Pure decision layer for the agent→Telegram file/image send
+ * (`send_file_to_user` MCP tool). Four concerns, all side-effect-free enough to
+ * unit-test without booting Telegraf:
+ *   1. {@link resolveSendFileWithinDir} — path-safety: resolve a caller-supplied
+ *      path against the topic's bound folder and confirm (realpath + containment)
+ *      it points at a REGULAR FILE inside it. Modeled on
+ *      `validation.ts:validateSubdir`, but for a file (not a directory) and
+ *      returning a discriminated result instead of throwing (the caller surfaces
+ *      the error to the agent as an MCP tool error).
+ *   2. {@link classifyFileSendKind} — map an extension to how Telegram should
+ *      render it (inline photo / autoplay animation / inline video / plain document).
+ *   3. {@link planFileSend} — decide the single Telegram send method (or album
+ *      shape) for 1..10 items, applying the `as_file` override, the photo size
+ *      downgrade, and the album photo/video-vs-document rule. Returns the
+ *      over-cap / count violations as an error variant rather than throwing.
+ *   4. {@link buildTelegramFileSendRequest} — turn a non-error plan into the
+ *      exact typed Bot API request shape, including caption placement.
+ *
+ * The only fs touch is the bigint `statSync` inside
+ * {@link resolveSendFileWithinDir} (unavoidable for the regular-file and
+ * identity gates). The caller supplies owned descriptor snapshots, so planning
+ * and request construction never carry workspace paths into Telegraf.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.videoExtensions = exports.animationExtensions = exports.photoExtensions = exports.captionMaxLength = exports.mediaGroupMax = exports.mediaGroupMin = exports.telegramSendMaxBytes = exports.telegramPhotoMaxBytes = void 0;
+exports.resolveSendFileWithinDir = resolveSendFileWithinDir;
+exports.classifyFileSendKind = classifyFileSendKind;
+exports.getTelegramUploadFilename = getTelegramUploadFilename;
+exports.trimCaption = trimCaption;
+exports.buildTelegramFileSendRequest = buildTelegramFileSendRequest;
+exports.getTelegramFileOversizeError = getTelegramFileOversizeError;
+exports.getFileSendCountError = getFileSendCountError;
+exports.planFileSend = planFileSend;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const canonicalPathContainment_1 = require("./canonicalPathContainment");
+/** Telegram's inline-photo size cap; a photo-eligible file over this downgrades to a document. */
+exports.telegramPhotoMaxBytes = 10 * 1024 * 1024;
+/** Bot API hard send cap per file; anything over this is rejected, never sent. */
+exports.telegramSendMaxBytes = 50 * 1024 * 1024;
+/** Minimum item count that forms a media-group album (below ⇒ single send). */
+exports.mediaGroupMin = 2;
+/** Maximum item count Telegram accepts in one media-group album. */
+exports.mediaGroupMax = 10;
+/** Telegram caption length cap (characters); longer captions are trimmed. */
+exports.captionMaxLength = 1024;
+/** Extensions rendered as inline photos (lowercased, leading dot). */
+exports.photoExtensions = ['.png', '.jpg', '.jpeg', '.webp'];
+/** Extensions rendered as looping animations (lowercased, leading dot). */
+exports.animationExtensions = ['.gif'];
+/** Extensions rendered with Telegram's native streaming video player. */
+exports.videoExtensions = ['.mp4'];
+/** Characters that cannot safely appear in a quoted multipart filename parameter. */
+const telegramUploadFilenameUnsafeCharacters = /[\x00-\x1f\x7f"\\]/g;
+/**
+ * @description Resolve `rawPath` against the topic's bound `workDir` and confirm
+ * it points at a regular file living inside it. A multi-file caller supplies
+ * `pinnedRootPath` after the first item so a replaced binding cannot become a
+ * new trusted root between album items. Defence-in-depth mirrors
+ * `validateSubdir`: reject control chars, NFC-normalise, canonicalize the root,
+ * then use the shared canonical candidate containment gate. The final gate differs: this is for a
+ * FILE, so `statSync` must report a regular file (a directory or socket is
+ * rejected, not accepted).
+ */
+function resolveSendFileWithinDir(workDir, rawPath, pinnedRootPath) {
+    if (/[\x00-\x1f]/.test(rawPath)) {
+        return { ok: false, code: 'INVALID_CHARS', error: `path contains control characters: ${JSON.stringify(rawPath)}` };
+    }
+    const normalised = rawPath.normalize('NFC').trim();
+    if (!normalised) {
+        return { ok: false, code: 'INVALID_CHARS', error: 'path is empty' };
+    }
+    let realRoot = pinnedRootPath;
+    if (realRoot === undefined) {
+        try {
+            realRoot = fs.realpathSync(workDir);
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : 'unknown error';
+            return { ok: false, code: 'NOT_FOUND', error: `bound folder vanished: ${errorMessage}` };
+        }
+    }
+    let canonicalCandidate;
+    let isWithinRoot;
+    try {
+        ({ canonicalPath: canonicalCandidate, isWithinRoot } =
+            (0, canonicalPathContainment_1.resolveCanonicalPathContainment)(realRoot, normalised));
+    }
+    catch {
+        return { ok: false, code: 'NOT_FOUND', error: `file not found: ${normalised}` };
+    }
+    if (!isWithinRoot) {
+        return { ok: false, code: 'OUTSIDE_FOLDER', error: `path resolves outside the bound folder: ${normalised}` };
+    }
+    let stat;
+    try {
+        stat = fs.statSync(canonicalCandidate, { bigint: true });
+    }
+    catch {
+        return { ok: false, code: 'NOT_FOUND', error: `file not found: ${normalised}` };
+    }
+    if (!stat.isFile()) {
+        return { ok: false, code: 'NOT_A_FILE', error: `not a regular file: ${normalised}` };
+    }
+    return {
+        ok: true,
+        absPath: canonicalCandidate,
+        rootPath: realRoot,
+        identity: { dev: stat.dev, ino: stat.ino },
+    };
+}
+/**
+ * @description Classify a path by its lowercased extension into the Telegram
+ * render kind. `.png/.jpg/.jpeg/.webp` → photo; `.gif` → animation; `.mp4` →
+ * video; anything else → document.
+ */
+function classifyFileSendKind(filePath) {
+    const ext = path.extname(filePath).toLowerCase();
+    if (exports.photoExtensions.includes(ext))
+        return 'photo';
+    if (exports.animationExtensions.includes(ext))
+        return 'animation';
+    if (exports.videoExtensions.includes(ext))
+        return 'video';
+    return 'document';
+}
+/** Derive a multipart-safe filename from a canonical file path. */
+function getTelegramUploadFilename(filePath) {
+    return path.basename(filePath).replace(telegramUploadFilenameUnsafeCharacters, '_');
+}
+/**
+ * @description Trim a caption to Telegram's {@link captionMaxLength} cap. Returns
+ * `undefined` for an absent/blank caption so callers can omit the field entirely.
+ */
+function trimCaption(caption) {
+    if (caption === undefined)
+        return undefined;
+    const trimmed = caption.length > exports.captionMaxLength ? caption.slice(0, exports.captionMaxLength) : caption;
+    return trimmed.length > 0 ? trimmed : undefined;
+}
+const telegramSingleFileSendMethods = {
+    photo: 'sendPhoto',
+    animation: 'sendAnimation',
+    video: 'sendVideo',
+    document: 'sendDocument',
+};
+/** Build one media-group entry's shared source/caption fields. */
+function buildTelegramAlbumMediaInput(item, index, caption) {
+    return {
+        media: item.source,
+        ...(index === 0 && caption !== undefined ? { caption } : {}),
+    };
+}
+/**
+ * @description Convert a non-error plan into the exact Telegram request the bot
+ * executes. Captions are trimmed here and included on a single request or only
+ * the first media-group entry. `albumPhotoVideo` accepts only photo/video items;
+ * an impossible hand-built plan throws a path-naming error instead of silently
+ * sending another kind as a photo.
+ */
+function buildTelegramFileSendRequest(plan, caption) {
+    const trimmedCaption = trimCaption(caption);
+    if (plan.kind === 'send') {
+        return {
+            method: telegramSingleFileSendMethods[plan.mode],
+            source: plan.item.source,
+            ...(trimmedCaption !== undefined ? { caption: trimmedCaption } : {}),
+        };
+    }
+    if (plan.mode === 'albumDocument') {
+        const media = plan.items.map((item, index) => ({
+            type: 'document',
+            ...buildTelegramAlbumMediaInput(item, index, trimmedCaption),
+        }));
+        return { method: 'sendMediaGroup', mediaGroup: { kind: 'document', media } };
+    }
+    const media = plan.items.map((item, index) => {
+        const mediaInput = buildTelegramAlbumMediaInput(item, index, trimmedCaption);
+        if (item.kind === 'photo')
+            return { type: 'photo', ...mediaInput };
+        if (item.kind === 'video')
+            return { type: 'video', ...mediaInput };
+        throw new Error(`albumPhotoVideo cannot contain ${item.kind}: ${item.absPath}`);
+    });
+    return { method: 'sendMediaGroup', mediaGroup: { kind: 'photoVideo', media } };
+}
+/** First item over the hard send cap, or `null` if all are within it. */
+function findOversizeItem(items) {
+    for (const item of items) {
+        if (item.source.sizeBytes > exports.telegramSendMaxBytes)
+            return item;
+    }
+    return null;
+}
+/** Existing user-facing hard-cap error shared by planning and snapshot reads. */
+function getTelegramFileOversizeError(absPath) {
+    const mb = (exports.telegramSendMaxBytes / (1024 * 1024)).toString();
+    return `file exceeds the ${mb} MB send limit: ${absPath}`;
+}
+/** Existing user-facing item-count validation shared by planning and the reader. */
+function getFileSendCountError(itemCount) {
+    if (itemCount === 0)
+        return 'no files to send';
+    if (itemCount > exports.mediaGroupMax) {
+        return `too many files: ${itemCount} (max ${exports.mediaGroupMax})`;
+    }
+    return null;
+}
+/**
+ * @description Decide how to deliver 1..10 resolved files.
+ *
+ * Single file: the method is the item's kind, with two overrides —
+ *  - `asFile` forces `document` for every kind, and
+ *  - a photo over {@link telegramPhotoMaxBytes} downgrades to `document` so it
+ *    still goes through (just not inline).
+ *
+ * Album (2..10): `albumPhotoVideo` when `!asFile` and EVERY item is either a
+ * video or a photo within the photo cap, preserving each item's native media
+ * type in all-photo, all-video, and mixed photo/video groups. Otherwise use
+ * `albumDocument` (animations/documents and over-cap photos included — a media
+ * group cannot carry animation items, so a gif rides as a document in an album
+ * and only autoplays when sent alone).
+ *
+ * Returns an `error` plan for 0 items, >{@link mediaGroupMax}, or any item over
+ * {@link telegramSendMaxBytes}.
+ */
+function planFileSend(items, asFile) {
+    const countError = getFileSendCountError(items.length);
+    if (countError !== null)
+        return { kind: 'error', error: countError };
+    const oversize = findOversizeItem(items);
+    if (oversize) {
+        return { kind: 'error', error: getTelegramFileOversizeError(oversize.absPath) };
+    }
+    if (items.length < exports.mediaGroupMin) {
+        const item = items[0];
+        let mode = item.kind;
+        if (asFile) {
+            mode = 'document';
+        }
+        else if (item.kind === 'photo' && item.source.sizeBytes > exports.telegramPhotoMaxBytes) {
+            // Too big for an inline photo → still deliver, as a document.
+            mode = 'document';
+        }
+        return { kind: 'send', mode, item };
+    }
+    const allPhotoVideoEligible = !asFile &&
+        items.every((item) => item.kind === 'video' ||
+            (item.kind === 'photo' && item.source.sizeBytes <= exports.telegramPhotoMaxBytes));
+    return {
+        kind: 'album',
+        mode: allPhotoVideoEligible ? 'albumPhotoVideo' : 'albumDocument',
+        items,
+    };
+}
+//# sourceMappingURL=fileSendPlan.js.map

package/dist/utils/fileSendPlan.js.map

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

package/dist/utils/fileSendService.d.ts

@@ -0,0 +1,94 @@
+/**
+ * @description Reusable agent→Telegram file-send pipeline. The factory owns the
+ * impure path resolution/snapshot work and executes the pure plan/request through
+ * an injected typed gateway. Each canonical file is opened component-by-component
+ * beneath a pinned root descriptor, identity-checked, and owned through delivery bookkeeping.
+ * Bot-specific stream creation and routing stay in the gateway; pacing/retry is
+ * injected through `executeDelivery`. The service imports neither MCP nor Telegraf.
+ */
+import { type FileDescriptorSnapshot, type FileIdentity, type FileSendMediaGroup } from './fileSendPlan';
+export interface SendFilesToThreadOptions {
+    paths: string[];
+    caption?: string;
+    asFile?: boolean;
+    /** Canonical directory granted by a directory-scoped MCP token. */
+    authorizedWorkDir?: string;
+    signal?: AbortSignal;
+}
+export type SendFilesToThreadResult = {
+    ok: true;
+    summary: string;
+} | {
+    ok: false;
+    error: string;
+} | {
+    ok: false;
+    kind: 'deliveryUnknown';
+    error: string;
+};
+/** Telegram may have accepted the request, but the response never confirmed it. */
+export declare class FileSendDeliveryUnknownError extends Error {
+    constructor(cause: Error);
+}
+export type SendFilesToThread = (threadKey: string, options: SendFilesToThreadOptions) => Promise<SendFilesToThreadResult>;
+export type FileSendTargetResolution<TTarget> = {
+    ok: true;
+    target: TTarget;
+    workDir: string;
+} | {
+    ok: false;
+    error: string;
+};
+export interface FileSendGatewayResult {
+    messageIds: number[];
+}
+export interface FileSendGateway<TTarget> {
+    sendPhoto: (target: TTarget, source: FileDescriptorSnapshot, caption?: string, signal?: AbortSignal) => Promise<FileSendGatewayResult>;
+    sendAnimation: (target: TTarget, source: FileDescriptorSnapshot, caption?: string, signal?: AbortSignal) => Promise<FileSendGatewayResult>;
+    sendVideo: (target: TTarget, source: FileDescriptorSnapshot, caption?: string, signal?: AbortSignal) => Promise<FileSendGatewayResult>;
+    sendDocument: (target: TTarget, source: FileDescriptorSnapshot, caption?: string, signal?: AbortSignal) => Promise<FileSendGatewayResult>;
+    sendMediaGroup: (target: TTarget, mediaGroup: FileSendMediaGroup, signal?: AbortSignal) => Promise<FileSendGatewayResult>;
+}
+export interface SendFilesToThreadDeps<TTarget> {
+    resolveTargetAndWorkDir: (threadKey: string) => FileSendTargetResolution<TTarget>;
+    gateway: FileSendGateway<TTarget>;
+    recordMessageIds: (target: TTarget, messageIds: number[]) => Promise<void>;
+    executeDelivery?: <TResult>(target: TTarget, delivery: () => Promise<TResult>, signal?: AbortSignal) => Promise<TResult>;
+    readFileSnapshot?: typeof readTelegramFileSnapshot;
+}
+/** Canonical send root pinned to one open directory descriptor. */
+export interface PinnedFileSendRoot {
+    rootPath: string;
+    fd: number;
+}
+/** Bound descriptor-owning operations while Telegram's own queues are occupied. */
+export declare const fileSendSnapshotConcurrency = 4;
+export type TelegramFileSnapshotResult = {
+    ok: true;
+    source: FileDescriptorSnapshot;
+} | {
+    ok: false;
+    kind: 'read';
+    error: string;
+} | {
+    ok: false;
+    kind: 'oversize';
+    error: string;
+};
+/** Linux exposes descriptor-relative child lookup; other platforms fail closed. */
+export declare function getFileDescriptorPathRoot(platform: NodeJS.Platform): string | null;
+/**
+ * @description Open one already-canonical path beneath its pinned canonical root
+ * without following swapped parent/final symlinks, validate the opened object's
+ * bigint device/inode identity and size, then transfer ownership of the still-open
+ * descriptor to the caller. Every failure closes the descriptor before returning.
+ */
+export declare function readTelegramFileSnapshot(absPath: string, expectedIdentity: FileIdentity, pinnedRoot: PinnedFileSendRoot): TelegramFileSnapshotResult;
+/**
+ * @description Compose the complete file-send operation around a target/workdir
+ * resolver and Telegram gateway. A gateway return confirms delivery; subsequent
+ * message-id persistence or descriptor cleanup failures are success warnings so
+ * callers do not retry and duplicate an already-delivered message or album.
+ */
+export declare function createSendFilesToThread<TTarget>(deps: SendFilesToThreadDeps<TTarget>): SendFilesToThread;
+//# sourceMappingURL=fileSendService.d.ts.map

package/dist/utils/fileSendService.d.ts.map

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