@qvac/harness 0.7.3 → 0.8.5

package/dist-lib/lib/tools/office.js

@@ -0,0 +1,486 @@
+import b4a from 'b4a';
+import { errorMessage, isRecord } from '../guards.js';
+import { docx, pptx, units, xlsx } from '../office/engine/index.js';
+import { stageInputs } from './exec/adapters/python/attachments.js';
+import { checkOutputBytes, RUN_OUTPUT_BUDGET_BYTES } from './exec/adapters/python/output-policy.js';
+import { DOCX_OPS, opArguments, opKeys, PPTX_OPS, withAliases, XLSX_OPS } from './office/ops.js';
+const READ_CELL_LIMIT = 10_000;
+const attachedThisTurn = new WeakMap();
+const FIRST_SHEET = /^sheet ?1$/i;
+const SHAPE_ROLES = new Set(['title', 'subtitle', 'body']);
+const HOISTED = ['attachmentId', 'output'];
+const WHERE_IDS_ARE = 'copy the id from the [Attached file "…" — attachmentId: …] line or an earlier tool result';
+function isObject(value) {
+    return isRecord(value) && !Array.isArray(value);
+}
+export function shapeFor(deck, op) {
+    const { shape, slide } = op;
+    if (typeof shape !== 'string' || SHAPE_ROLES.has(shape) || typeof slide !== 'number') {
+        return op;
+    }
+    if (/^\d+$/.test(shape)) {
+        return { ...op, shape: Number(shape) };
+    }
+    const wanted = shape.trim().toLowerCase();
+    const found = deck.read()[slide]?.shapes.find((entry) => entry.name.toLowerCase() === wanted);
+    return found && found.id !== null ? { ...op, shape: found.id } : op;
+}
+export function sheetFor(book, op, created) {
+    if (typeof op.sheet !== 'string')
+        return op;
+    const sheets = book.sheets();
+    if (sheets.some((sheet) => sheet.name === op.sheet)) {
+        return op;
+    }
+    const only = sheets.length === 1 ? sheets[0] : undefined;
+    if (!only) {
+        return op;
+    }
+    if (FIRST_SHEET.test(op.sheet)) {
+        return { ...op, sheet: only.name };
+    }
+    if (created && FIRST_SHEET.test(only.name) && book.read(only.index).rows.length === 0) {
+        book.renameSheet(only.index, op.sheet);
+    }
+    return op;
+}
+function readWorkbook(book) {
+    const sheets = book.sheets();
+    const read = [];
+    let budget = READ_CELL_LIMIT;
+    for (const sheet of sheets) {
+        if (sheet.kind !== 'worksheet')
+            continue;
+        if (budget <= 0) {
+            read.push({ name: sheet.name, range: sheet.range ?? null, truncated: true });
+            continue;
+        }
+        const contents = book.read(sheet.index, { limit: budget });
+        budget -= contents.rows.reduce((cells, row) => cells + row.length, 0);
+        read.push(contents);
+    }
+    return { sheets, read };
+}
+const PPTX_FORMAT = {
+    name: 'pptx',
+    noun: 'PowerPoint deck',
+    ops: PPTX_OPS,
+    createKeys: ['size', 'title', 'fonts', 'colors'],
+    open: (bytes) => pptx.open(bytes),
+    create: (options) => pptx.create(options),
+    read: (deck) => deck.read(),
+    count: (deck) => ({ slides: deck.slideCount }),
+    prepare: (deck, op) => shapeFor(deck, op)
+};
+const DOCX_FORMAT = {
+    name: 'docx',
+    noun: 'Word document',
+    ops: DOCX_OPS,
+    createKeys: ['title', 'page', 'size', 'fonts'],
+    open: (bytes) => docx.open(bytes),
+    create: (options) => docx.create(options),
+    read: (doc) => doc.read(),
+    count: (doc) => ({ blocks: doc.blockCount })
+};
+const XLSX_FORMAT = {
+    name: 'xlsx',
+    noun: 'Excel workbook',
+    ops: XLSX_OPS,
+    createKeys: ['sheets', 'title'],
+    open: (bytes) => xlsx.open(bytes),
+    create: (options) => xlsx.create(options),
+    read: readWorkbook,
+    count: (book) => ({ sheets: book.sheets().length }),
+    prepare: (book, op, created) => sheetFor(book, op, created),
+    beforeSave: (book) => book.hasMacros
+        ? 'the workbook has macros, which cannot be saved as .xlsx — add a removeMacros op'
+        : null
+};
+export function normalizeArgs(args) {
+    if (!Array.isArray(args.ops))
+        return args;
+    const lifted = { ...args };
+    const ops = [];
+    for (const entry of args.ops) {
+        const op = typeof entry === 'string' ? { op: entry } : entry;
+        if (!isObject(op)) {
+            ops.push(op);
+            continue;
+        }
+        const rest = { ...op };
+        for (const key of HOISTED) {
+            if (key in rest && lifted[key] === undefined) {
+                lifted[key] = rest[key];
+                delete rest[key];
+            }
+        }
+        if (rest.op === 'create' && lifted.create === undefined && lifted.attachmentId === undefined) {
+            const { op: _create, ...options } = rest;
+            lifted.create = options;
+            continue;
+        }
+        ops.push(rest);
+    }
+    lifted.ops = ops;
+    return lifted;
+}
+function parseOp(format, op, i) {
+    if (!isObject(op) || typeof op.op !== 'string') {
+        return `ops[${i}] must be { op, ...args }`;
+    }
+    const spec = format.ops[op.op];
+    if (!spec) {
+        return `ops[${i}]: unknown op "${op.op}"; ops are ${Object.keys(format.ops).join(', ')}`;
+    }
+    const keys = opKeys(spec);
+    const unknown = Object.keys(op).filter((key) => key !== 'op' && !keys.includes(key));
+    if (!unknown.length) {
+        return { name: op.op, spec, args: withAliases(spec, op) };
+    }
+    if (op.op === 'sheets' && 'name' in op && format.ops.addSheet) {
+        return `ops[${i}] sheets lists the sheets and takes no arguments; to add a sheet use { op: "addSheet", name }`;
+    }
+    const takes = keys.length ? `it takes ${keys.join(', ')}` : 'it takes no arguments';
+    return `ops[${i}] ${op.op} does not take ${unknown.join(', ')}; ${takes}`;
+}
+function parseOps(format, ops) {
+    if (!Array.isArray(ops)) {
+        return 'ops must be an array of { op, ...args }';
+    }
+    const parsed = [];
+    for (const [i, op] of ops.entries()) {
+        const result = parseOp(format, op, i);
+        if (typeof result === 'string') {
+            return result;
+        }
+        parsed.push(result);
+    }
+    return parsed;
+}
+function argumentError(format, args) {
+    const { attachmentId, create, output } = args;
+    if (attachmentId !== undefined && (typeof attachmentId !== 'string' || !attachmentId)) {
+        return 'attachmentId must be a non-empty string';
+    }
+    if (create !== undefined && !isObject(create)) {
+        return 'create must be an object';
+    }
+    if (attachmentId !== undefined && create !== undefined) {
+        return `pass attachmentId to open a ${format.noun}, or create to start one — not both`;
+    }
+    const unknownCreate = Object.keys(create ?? {}).filter((key) => !format.createKeys.includes(key));
+    if (unknownCreate.length) {
+        return `create does not take ${unknownCreate.join(', ')}; it takes ${format.createKeys.join(', ')}`;
+    }
+    if (output !== undefined && (typeof output !== 'string' || !output)) {
+        return 'output must be a file name';
+    }
+    return null;
+}
+function parseRequest(format, raw) {
+    const args = normalizeArgs(raw);
+    const error = argumentError(format, args);
+    if (error) {
+        return error;
+    }
+    const ops = parseOps(format, args.ops ?? []);
+    if (typeof ops === 'string') {
+        return ops;
+    }
+    const attachmentId = typeof args.attachmentId === 'string' ? args.attachmentId : undefined;
+    if (attachmentId === undefined && !ops.length) {
+        return `nothing to read: pass the attachmentId of a ${format.noun} (${WHERE_IDS_ARE}), or ops to build one`;
+    }
+    return {
+        attachmentId,
+        create: isObject(args.create) ? args.create : undefined,
+        ops,
+        output: typeof args.output === 'string' ? args.output : undefined
+    };
+}
+async function sourceDocument(format, request, ctx) {
+    if (request.attachmentId === undefined) {
+        return { document: format.create(request.create ?? {}), fileName: null };
+    }
+    const found = await ctx.fetchAttachment?.({
+        attachmentId: request.attachmentId,
+        signal: ctx.signal
+    });
+    if (!found || !('bytes' in found)) {
+        return {
+            error: `attachment ${request.attachmentId} not found in this chat; ${WHERE_IDS_ARE}, not a file name`
+        };
+    }
+    return { document: format.open(found.bytes), fileName: found.fileName };
+}
+export function revisedName(format, fileName) {
+    const dot = fileName.lastIndexOf('.');
+    const stem = dot > 0 ? fileName.slice(0, dot) : fileName;
+    if (format === 'pptx') {
+        const version = /^(.*)-v(\d+)$/.exec(stem);
+        return version ? `${version[1]}-v${Number(version[2]) + 1}.pptx` : `${stem}-v2.pptx`;
+    }
+    const revised = /^(.*)_revised(?:-(\d+))?$/.exec(stem);
+    if (!revised) {
+        return `${stem}_revised.${format}`;
+    }
+    return `${revised[1]}_revised-${Number(revised[2] ?? 1) + 1}.${format}`;
+}
+function outputFor(format, output, input) {
+    if (!input)
+        return output;
+    if (output && output.toLowerCase() !== input.toLowerCase())
+        return output;
+    return revisedName(format, input);
+}
+async function imageId(ctx, id) {
+    const found = await ctx.fetchAttachment?.({ attachmentId: id, meta: true, signal: ctx.signal });
+    if (found) {
+        return id;
+    }
+    const latest = await ctx.fetchAttachment?.({ meta: true, signal: ctx.signal });
+    return latest && latest.fileName.toLowerCase() === id.toLowerCase() ? undefined : id;
+}
+async function imageInput(op, i, ctx) {
+    const image = op.args.image ?? {};
+    if (!isObject(image)) {
+        return { error: `ops[${i}]: image must be { attachmentId } or {}` };
+    }
+    const id = image.attachmentId;
+    if (id !== undefined && (typeof id !== 'string' || !id)) {
+        return { error: `ops[${i}]: image.attachmentId must be a non-empty string` };
+    }
+    return { attachmentId: id ? await imageId(ctx, id) : undefined, path: `image-${i}.png` };
+}
+async function stagedImages(request, ctx) {
+    const wanted = request.ops.flatMap((op, i) => (opKeys(op.spec).includes('image') ? [i] : []));
+    const images = new Map();
+    if (!wanted.length) {
+        return images;
+    }
+    if (!ctx.fetchAttachment) {
+        return { error: 'this device cannot read chat images' };
+    }
+    const inputs = [];
+    for (const i of wanted) {
+        const op = request.ops[i];
+        const input = op ? await imageInput(op, i, ctx) : { error: `ops[${i}] is missing` };
+        if ('error' in input) {
+            return input;
+        }
+        inputs.push(input);
+    }
+    const staged = await stageInputs(ctx.fetchAttachment, inputs, {
+        turnImages: ctx.turnImages,
+        signal: ctx.signal
+    });
+    if ('error' in staged) {
+        return staged;
+    }
+    for (const [n, file] of staged.files.entries()) {
+        const at = wanted[n];
+        if (at !== undefined) {
+            images.set(at, file.bytes);
+        }
+    }
+    return images;
+}
+function saveError({ format, document, output }, ctx) {
+    if (!output) {
+        return `the ops changed the ${format.noun}; name the file in output`;
+    }
+    if (!output.toLowerCase().endsWith(`.${format.name}`)) {
+        return `output must end in .${format.name}, got "${output}"`;
+    }
+    const refusal = format.beforeSave?.(document);
+    if (refusal) {
+        return refusal;
+    }
+    return ctx.attach ? null : `this device cannot attach a ${format.noun} to the chat`;
+}
+async function attachOutput(job, ctx) {
+    const refused = saveError(job, ctx);
+    if (refused || !job.output || !ctx.attach) {
+        return { error: refused ?? 'nothing to save' };
+    }
+    const { output, document } = job;
+    const delivered = attachedThisTurn.get(ctx.attach) ?? new Map();
+    const earlier = delivered.get(output.toLowerCase());
+    const bytes = document.save();
+    if (earlier && b4a.equals(earlier.bytes, bytes)) {
+        return { attachment: earlier.attachment, repeated: true };
+    }
+    if (earlier) {
+        return {
+            error: `${earlier.attachment.fileName} is already attached with different content; save this version under a new name in output`
+        };
+    }
+    const verdict = checkOutputBytes(output, bytes, 0);
+    if ('error' in verdict) {
+        return verdict;
+    }
+    const budget = ctx.runBudget;
+    if (budget && budget.outputBytesUsed + bytes.byteLength > RUN_OUTPUT_BUDGET_BYTES) {
+        return { error: 'run output budget exceeded' };
+    }
+    const record = await ctx.attach({
+        fileName: output,
+        mimeType: verdict.mimeType,
+        bytes,
+        raw: true
+    });
+    if (budget) {
+        budget.outputBytesUsed += bytes.byteLength;
+    }
+    const attachment = {
+        attachmentId: record.id,
+        fileName: record.fileName,
+        byteLength: record.byteLength
+    };
+    delivered.set(output.toLowerCase(), { attachment, bytes });
+    attachedThisTurn.set(ctx.attach, delivered);
+    return { attachment, repeated: false };
+}
+function runOp(document, op, input) {
+    const method = Reflect.get(document, op.name);
+    if (typeof method !== 'function') {
+        throw new Error(`${op.name} is not available on this file`);
+    }
+    return Reflect.apply(method, document, opArguments(op.spec, input, units.inches));
+}
+function runOps({ format, document, request, images }) {
+    const results = [];
+    const created = request.attachmentId === undefined;
+    for (const [i, op] of request.ops.entries()) {
+        const placed = format.prepare?.(document, op.args, created) ?? op.args;
+        const input = images.has(i) ? { ...placed, image: images.get(i) } : placed;
+        try {
+            results.push(runOp(document, op, input));
+        }
+        catch (err) {
+            return { error: `ops[${i}] ${op.name}: ${errorMessage(err)}` };
+        }
+    }
+    return results;
+}
+function countLine(counts) {
+    return Object.entries(counts)
+        .map(([noun, n]) => `${n} ${n === 1 ? noun.replace(/s$/, '') : noun}`)
+        .join(', ');
+}
+function describe(format) {
+    const queries = Object.keys(format.ops).filter((name) => format.ops[name]?.query);
+    const edits = Object.keys(format.ops).filter((name) => !format.ops[name]?.query);
+    const inches = Object.values(format.ops).some((spec) => spec.inches)
+        ? ' Positions and sizes (x, y, width, height) are inches.'
+        : '';
+    return (`Read, edit or create a ${format.noun} (.${format.name}). With attachmentId alone it ` +
+        `returns the ${format.noun}'s contents. ops run office engine methods in order, each ` +
+        `{ op, ...named args }: ${queries.join(', ')} return data; ${edits.join(', ')} change the ` +
+        'file. When anything changed, the result is saved as a chat attachment named output and ' +
+        'shown to the user automatically. A failing op saves nothing and its error names what ' +
+        `exists, so fix the call from it.${inches}`);
+}
+function parameters(format) {
+    return {
+        type: 'object',
+        properties: {
+            attachmentId: {
+                type: 'string',
+                description: `The ${format.noun} in this chat; omit it to create a new one`
+            },
+            create: {
+                type: 'object',
+                description: `Options for a new ${format.noun}: ${format.createKeys.join(', ')}`
+            },
+            ops: {
+                type: 'array',
+                description: 'Operations to run in order, each { op, ...named args }',
+                items: {
+                    type: 'object',
+                    properties: { op: { type: 'string', enum: Object.keys(format.ops) } },
+                    required: ['op']
+                }
+            },
+            output: {
+                type: 'string',
+                description: `File name for the saved ${format.noun}, ending in .${format.name}`
+            }
+        }
+    };
+}
+async function execute(format, args, ctx) {
+    const request = parseRequest(format, args);
+    if (typeof request === 'string') {
+        return { error: request };
+    }
+    if (request.attachmentId !== undefined && !ctx.fetchAttachment) {
+        return { error: 'this device cannot read chat attachments' };
+    }
+    const images = await stagedImages(request, ctx);
+    if ('error' in images) {
+        return images;
+    }
+    let source;
+    try {
+        source = await sourceDocument(format, request, ctx);
+    }
+    catch (err) {
+        return { error: errorMessage(err) };
+    }
+    if ('error' in source) {
+        return source;
+    }
+    const { document, fileName } = source;
+    if (!request.ops.length) {
+        return { document: format.read(document) };
+    }
+    const results = runOps({ format, document, request, images });
+    if ('error' in results) {
+        return results;
+    }
+    if (!document.changed && request.attachmentId !== undefined) {
+        return { results };
+    }
+    const output = outputFor(format.name, request.output, fileName);
+    const saved = await attachOutput({ format, document, output }, ctx);
+    if ('error' in saved) {
+        return saved;
+    }
+    const { attachment, repeated } = saved;
+    const counts = format.count(document);
+    const renamed = output !== request.output
+        ? `Saved as ${output}, so the attached ${fileName} keeps its own name. `
+        : '';
+    return {
+        results,
+        attachments: [attachment],
+        ...counts,
+        reply: `${attachment.fileName} — ${countLine(counts)}`,
+        next: renamed +
+            `Done: ${attachment.fileName} ${repeated ? 'was already' : 'is'} attached to the chat and shown to the user. ` +
+            `Do not call ${format.name} again for it. Your answer is the reply value alone, word for word.`
+    };
+}
+function createOfficeTool(format) {
+    return {
+        name: format.name,
+        toolset: null,
+        skillGated: true,
+        description: describe(format),
+        parameters: parameters(format),
+        effect: () => 'read',
+        validate(args) {
+            const request = parseRequest(format, args);
+            return typeof request === 'string' ? request : null;
+        },
+        execute: (args, ctx = {}) => execute(format, args, ctx)
+    };
+}
+export function createOfficeTools() {
+    return [
+        createOfficeTool(PPTX_FORMAT),
+        createOfficeTool(DOCX_FORMAT),
+        createOfficeTool(XLSX_FORMAT)
+    ];
+}

package/dist-lib/lib/tools/pdf/build.d.ts

@@ -0,0 +1,43 @@
+import type { PdfRequest } from './request.ts';
+export type Pdfium = typeof import('bare-pdfium');
+export type Doc = ReturnType<Pdfium['open']>;
+type Field = ReturnType<Doc['fields']>[number];
+export interface Source {
+    readonly attachmentId: string;
+    readonly fileName: string;
+    readonly bytes: Uint8Array;
+}
+export interface Opened {
+    readonly source: Source;
+    readonly doc: Doc;
+}
+export interface Built {
+    readonly bytes: Uint8Array;
+    readonly pageCount: number;
+}
+export interface ReadField {
+    readonly name: string;
+    readonly type: string;
+    readonly value: Field['value'];
+    readonly options: readonly string[] | undefined;
+    readonly readOnly: true | undefined;
+}
+export interface ReadDocument {
+    readonly attachmentId: string;
+    readonly fileName: string;
+    readonly pageCount: number;
+    readonly pages: readonly {
+        page: number;
+        text: string;
+    }[];
+    readonly fields: readonly ReadField[];
+    readonly note: string | undefined;
+    readonly truncated: true | undefined;
+}
+export interface ReadDocuments {
+    readonly documents: readonly ReadDocument[];
+}
+export declare function pagesLabel(count: number): string;
+export declare function readDocs(opened: readonly Opened[]): ReadDocument | ReadDocuments;
+export declare function build(pdfium: Pdfium, request: PdfRequest, opened: readonly Opened[]): Built | string;
+export {};

package/dist-lib/lib/tools/pdf/build.js

@@ -0,0 +1,150 @@
+import b4a from 'b4a';
+const READ_TEXT_LIMIT = 30_000;
+function plural(count, noun) {
+    return `${count} ${noun}${count === 1 ? '' : 's'}`;
+}
+export function pagesLabel(count) {
+    return plural(count, 'page');
+}
+function zeroBased(opened, pages) {
+    if (!pages) {
+        return Array.from({ length: opened.doc.pageCount() }, (_, page) => page);
+    }
+    const count = opened.doc.pageCount();
+    const outside = pages.filter((page) => page < 1 || page > count);
+    if (outside.length) {
+        return `${opened.source.fileName} has ${pagesLabel(count)}, numbered 1 to ${count}; there is no page ${outside.join(', ')}`;
+    }
+    return pages.map((page) => page - 1);
+}
+function describeField(field) {
+    return {
+        name: field.name,
+        type: field.type,
+        value: field.value,
+        options: field.options,
+        readOnly: field.readOnly || undefined
+    };
+}
+function scannedNote(scanned) {
+    if (!scanned.length)
+        return undefined;
+    const one = scanned.length === 1;
+    return `${one ? 'page' : 'pages'} ${scanned.join(', ')} ${one ? 'has' : 'have'} no text layer: ${one ? 'it is a scanned image' : 'they are scanned images'}, and there is no OCR here`;
+}
+function readOne({ source, doc }, budget) {
+    const pages = [];
+    const scanned = [];
+    let truncated = false;
+    for (const { page, text } of doc.textPages()) {
+        const clean = text.replace(/\r\n?/g, '\n').trim();
+        if (!clean) {
+            scanned.push(page + 1);
+        }
+        const kept = clean.slice(0, Math.max(0, budget.chars));
+        budget.chars -= kept.length;
+        truncated ||= kept.length < clean.length;
+        if (budget.chars > 0 || kept) {
+            pages.push({ page: page + 1, text: kept });
+        }
+    }
+    return {
+        attachmentId: source.attachmentId,
+        fileName: source.fileName,
+        pageCount: doc.pageCount(),
+        pages,
+        fields: doc.fields().map(describeField),
+        note: scannedNote(scanned),
+        truncated: truncated || undefined
+    };
+}
+export function readDocs(opened) {
+    const budget = { chars: READ_TEXT_LIMIT };
+    const documents = opened.map((one) => readOne(one, budget));
+    const [only] = documents;
+    return documents.length === 1 && only ? only : { documents };
+}
+function fromDoc(doc, bytes) {
+    return { bytes, pageCount: doc.pageCount() };
+}
+function joinPages(pdfium, parts, pages) {
+    const out = pdfium.create();
+    try {
+        for (const part of parts) {
+            out.importPages(part.doc, { pages });
+        }
+        return fromDoc(out, out.save());
+    }
+    finally {
+        out.close();
+    }
+}
+function textFile({ source, doc }) {
+    const text = [...doc.textPages()]
+        .map((page) => page.text.replace(/\r\n?/g, '\n').trim())
+        .join('\n\n');
+    if (!text.trim()) {
+        return `${source.fileName} has no text layer: its pages are scanned images, and there is no OCR here`;
+    }
+    return { bytes: b4a.from(text + '\n', 'utf8'), pageCount: doc.pageCount() };
+}
+function create(pdfium, request) {
+    const encrypt = request.password ? { password: request.password } : undefined;
+    const bytes = pdfium.compose(request.markdown, {
+        pageSize: request.pageSize,
+        landscape: request.landscape,
+        pageNumbers: request.pageNumbers,
+        encrypt
+    });
+    return { bytes, pageCount: pdfium.pageCount(bytes, { password: request.password }) };
+}
+function editOne(opened, request) {
+    const { doc } = opened;
+    switch (request.action) {
+        case 'rotate':
+        case 'watermark': {
+            const pages = zeroBased(opened, request.pages);
+            if (typeof pages === 'string') {
+                return pages;
+            }
+            if (request.action === 'rotate') {
+                doc.rotate(request.degrees, { pages });
+            }
+            else {
+                doc.watermark(request.text, { pages, opacity: request.opacity, position: request.position });
+            }
+            return fromDoc(doc, doc.save());
+        }
+        case 'fill':
+            doc.fillFields(request.values);
+            return fromDoc(doc, doc.save());
+        case 'encrypt': {
+            const password = request.password ?? '';
+            const { ownerPassword, permissions } = request;
+            return fromDoc(doc, doc.save({ encrypt: { password, ownerPassword, permissions } }));
+        }
+        case 'decrypt':
+            return fromDoc(doc, doc.save({ removeSecurity: true }));
+        case 'text':
+            return textFile(opened);
+        default:
+            return `${request.action} is not an edit`;
+    }
+}
+export function build(pdfium, request, opened) {
+    const [first] = opened;
+    if (request.action === 'create') {
+        return create(pdfium, request);
+    }
+    if (!first) {
+        return 'no PDF to work on';
+    }
+    if (request.action === 'merge') {
+        return joinPages(pdfium, opened);
+    }
+    if (request.action !== 'split') {
+        return editOne(first, request);
+    }
+    const pages = zeroBased(first, request.pages);
+    return typeof pages === 'string' ? pages : joinPages(pdfium, [first], pages);
+}

package/dist-lib/lib/tools/pdf/images.d.ts

@@ -0,0 +1,7 @@
+import type { ToolExecuteContext } from '../../capabilities/completion.ts';
+import { type CreateRequest } from './request.ts';
+interface ToolError {
+    readonly error: string;
+}
+export declare function placeImages(request: CreateRequest, ctx: ToolExecuteContext): Promise<CreateRequest | ToolError>;
+export {};