@qvac/harness 1.0.0-rc.0 → 1.0.0-rc.2

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 '../../contract/index.ts';
+import { type CreateRequest } from './request.ts';
+interface ToolError {
+    readonly error: string;
+}
+export declare function placeImages(request: CreateRequest, ctx: ToolExecuteContext): Promise<CreateRequest | ToolError>;
+export {};

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

@@ -0,0 +1,82 @@
+import b4a from 'b4a';
+import { stageInputs } from '../attachments/staging.js';
+import { WHERE_IDS_ARE } from './request.js';
+const IMAGE_REF = /!\[([^\]\n]*)\]\(\s*<?([^)\s>]+)>?(?:\s+"[^"]*")?\s*\)/g;
+const LINKED = /^(?:data:|https?:)/i;
+const LOOKS_LIKE_ID = /^[0-9a-f]{6,}$/i;
+const FIRST_HEADING = /^#{1,6}\s.*$/m;
+function mimeOf(bytes) {
+    if (bytes[0] === 0x89 && bytes[1] === 0x50 && bytes[2] === 0x4e && bytes[3] === 0x47) {
+        return 'image/png';
+    }
+    return bytes[0] === 0xff && bytes[1] === 0xd8 ? 'image/jpeg' : null;
+}
+function notAnImage(id, bytes) {
+    const name = id ?? 'the uploaded file';
+    if (b4a.toString(bytes.subarray(0, 5), 'latin1') === '%PDF-') {
+        return `${name} is a PDF, not an image; create makes a new PDF from markdown, so read that PDF and write its content into the markdown`;
+    }
+    return `${name} is not a PNG or JPEG image`;
+}
+function withIds(markdown, ids) {
+    const missing = ids.filter((id) => !markdown.includes(`](${id})`));
+    if (!missing.length) {
+        return markdown;
+    }
+    const images = missing.map((id) => `![](${id})`).join('\n\n');
+    const heading = FIRST_HEADING.exec(markdown);
+    if (!heading) {
+        return `${images}\n\n${markdown}`;
+    }
+    const end = heading.index + heading[0].length;
+    return `${markdown.slice(0, end)}\n\n${images}\n\n${markdown.slice(end).replace(/^\n+/, '')}`;
+}
+async function refOf(alt, target, ctx) {
+    const id = target.replace(/^attachment(?:Id)?:/i, '');
+    const found = await ctx.fetchAttachment?.({ attachmentId: id, meta: true, signal: ctx.signal });
+    if (found) {
+        return { alt, attachmentId: id };
+    }
+    if (LOOKS_LIKE_ID.test(id)) {
+        return {
+            error: `image ${id} not found in this chat; ${WHERE_IDS_ARE}, or name the user's uploaded image by its file name`
+        };
+    }
+    return { alt, attachmentId: undefined };
+}
+async function stage(refs, ctx) {
+    if (!ctx.fetchAttachment) {
+        return { error: 'this device cannot read chat images' };
+    }
+    return stageInputs(ctx.fetchAttachment, refs.map((ref, i) => ({ attachmentId: ref.attachmentId, path: `image-${i}.png` })), { turnImages: ctx.turnImages, signal: ctx.signal });
+}
+export async function placeImages(request, ctx) {
+    const markdown = withIds(request.markdown, request.ids);
+    const matches = [...markdown.matchAll(IMAGE_REF)].filter((match) => !LINKED.test(match[2] ?? ''));
+    if (!matches.length) {
+        return { ...request, markdown, ids: [] };
+    }
+    const refs = [];
+    for (const match of matches) {
+        const ref = await refOf(match[1] ?? '', match[2] ?? '', ctx);
+        if ('error' in ref) {
+            return ref;
+        }
+        refs.push(ref);
+    }
+    const staged = await stage(refs, ctx);
+    if ('error' in staged) {
+        return staged;
+    }
+    const uris = [];
+    for (const [i, file] of staged.files.entries()) {
+        const mime = mimeOf(file.bytes);
+        if (!mime) {
+            return { error: notAnImage(refs[i]?.attachmentId, file.bytes) };
+        }
+        uris.push(`data:${mime};base64,${b4a.toString(file.bytes, 'base64')}`);
+    }
+    let n = 0;
+    const placed = markdown.replace(IMAGE_REF, (whole, alt, target) => LINKED.test(target) ? whole : `\n\n![${alt}](${uris[n++] ?? target})\n\n`);
+    return { ...request, markdown: placed, ids: [] };
+}

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

@@ -0,0 +1,63 @@
+export declare const PDF_ACTIONS: readonly ['create', 'merge', 'split', 'rotate', 'watermark', 'fill', 'encrypt', 'decrypt', 'text'];
+export declare const PAGE_SIZES: readonly ['A4', 'A5', 'Letter', 'Legal'];
+export declare const DEGREES: readonly [90, 180, 270];
+export declare const WHERE_IDS_ARE = "copy the id from the [Attached file \"\u2026\" \u2014 attachmentId: \u2026] line or an earlier tool result";
+export type Action = (typeof PDF_ACTIONS)[number];
+export type PageSize = (typeof PAGE_SIZES)[number];
+export type FieldValue = string | number | boolean | string[];
+export interface Permissions {
+    print?: boolean;
+    modify?: boolean;
+    copy?: boolean;
+    annotate?: boolean;
+    fillForms?: boolean;
+    extract?: boolean;
+    assemble?: boolean;
+    printHighQuality?: boolean;
+}
+interface Common {
+    readonly ids: readonly string[];
+    readonly password: string | undefined;
+    readonly output: string | undefined;
+}
+export type PdfRequest = (Common & {
+    readonly action: 'read';
+}) | (Common & {
+    readonly action: 'create';
+    readonly markdown: string;
+    readonly pageSize: PageSize | undefined;
+    readonly landscape: boolean;
+    readonly pageNumbers: boolean;
+}) | (Common & {
+    readonly action: 'merge' | 'decrypt' | 'text';
+}) | (Common & {
+    readonly action: 'split';
+    readonly pages: readonly number[];
+}) | (Common & {
+    readonly action: 'rotate';
+    readonly degrees: number;
+    readonly pages: readonly number[] | undefined;
+}) | (Common & {
+    readonly action: 'watermark';
+    readonly text: string;
+    readonly opacity: number | undefined;
+    readonly position: 'over' | 'under' | undefined;
+    readonly pages: readonly number[] | undefined;
+}) | (Common & {
+    readonly action: 'fill';
+    readonly values: Record<string, FieldValue>;
+}) | (Common & {
+    readonly action: 'encrypt';
+    readonly ownerPassword: string | undefined;
+    readonly permissions: Permissions | undefined;
+});
+export type CreateRequest = Extract<PdfRequest, {
+    action: 'create';
+}>;
+export declare function parsePages(value: unknown): number[] | string;
+type Args = Record<string, unknown>;
+export declare function impliedAction(args: Args): Action | 'read';
+export declare function pageSizeOf(value: unknown): PageSize | undefined;
+export declare function quarterTurn(value: unknown): number | undefined;
+export declare function parseRequest(args: Record<string, unknown>): PdfRequest | string;
+export {};

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

@@ -0,0 +1,335 @@
+import { isRecord } from '../../guards.js';
+export const PDF_ACTIONS = [
+    'create',
+    'merge',
+    'split',
+    'rotate',
+    'watermark',
+    'fill',
+    'encrypt',
+    'decrypt',
+    'text'
+];
+export const PAGE_SIZES = ['A4', 'A5', 'Letter', 'Legal'];
+export const DEGREES = [90, 180, 270];
+export const WHERE_IDS_ARE = 'copy the id from the [Attached file "…" — attachmentId: …] line or an earlier tool result';
+const MAX_PAGE_SPAN = 10_000;
+const PAGES_HINT = 'pages must be page numbers counted from 1, like [1, 2, 3]';
+function pageRange(part) {
+    const range = /^\s*(\d+)\s*(?:-\s*(\d+)\s*)?$/.exec(part);
+    if (!range) {
+        return null;
+    }
+    const from = Number(range[1]);
+    const to = Number(range[2] ?? range[1]);
+    if (Math.abs(to - from) > MAX_PAGE_SPAN) {
+        return null;
+    }
+    const step = from <= to ? 1 : -1;
+    const pages = [from];
+    for (let page = from; page !== to; page += step) {
+        pages.push(page + step);
+    }
+    return pages;
+}
+function pageItem(item) {
+    if (typeof item === 'number') {
+        return Number.isInteger(item) ? [item] : null;
+    }
+    if (typeof item !== 'string')
+        return null;
+    const pages = [];
+    for (const part of item.split(',')) {
+        const range = pageRange(part);
+        if (!range) {
+            return null;
+        }
+        pages.push(...range);
+    }
+    return pages;
+}
+export function parsePages(value) {
+    const items = Array.isArray(value) ? value : [value];
+    if (!items.length) {
+        return PAGES_HINT;
+    }
+    const pages = [];
+    for (const item of items) {
+        const parsed = pageItem(item);
+        if (!parsed) {
+            return PAGES_HINT;
+        }
+        pages.push(...parsed);
+    }
+    return pages;
+}
+function optionalPages(value) {
+    if (value === undefined || value === null)
+        return undefined;
+    const pages = parsePages(value);
+    return typeof pages === 'string' ? { error: pages } : pages;
+}
+function textOf(value) {
+    if (typeof value === 'number') {
+        return String(value);
+    }
+    return typeof value === 'string' && value.trim() ? value : undefined;
+}
+function idsOf(args) {
+    const list = [];
+    if (args.attachmentId !== undefined && args.attachmentId !== null) {
+        list.push(args.attachmentId);
+    }
+    if (Array.isArray(args.attachmentIds)) {
+        list.push(...args.attachmentIds);
+    }
+    else if (args.attachmentIds !== undefined && args.attachmentIds !== null) {
+        return { error: 'attachmentIds must be an array of ids' };
+    }
+    const ids = [];
+    for (const id of list) {
+        if (typeof id !== 'string' || !id.trim()) {
+            return { error: 'attachment ids must be non-empty strings' };
+        }
+        if (!ids.includes(id.trim())) {
+            ids.push(id.trim());
+        }
+    }
+    return ids;
+}
+function isAction(name) {
+    return PDF_ACTIONS.some((action) => action === name);
+}
+function hasOutput(args, extension) {
+    return typeof args.output === 'string' && args.output.trim().toLowerCase().endsWith(extension);
+}
+function idCount(args) {
+    const many = Array.isArray(args.attachmentIds) ? args.attachmentIds.length : 0;
+    return many + (typeof args.attachmentId === 'string' ? 1 : 0);
+}
+const IMPLIED = [
+    [(args) => typeof args.markdown === 'string', 'create'],
+    [(args) => args.degrees !== undefined, 'rotate'],
+    [(args) => args.values !== undefined, 'fill'],
+    [(args) => typeof args.text === 'string', 'watermark'],
+    [(args) => args.ownerPassword !== undefined || args.permissions !== undefined, 'encrypt'],
+    [(args) => hasOutput(args, '.txt'), 'text'],
+    [(args) => hasOutput(args, '.pdf') && idCount(args) > 1, 'merge'],
+    [(args) => hasOutput(args, '.pdf') && args.pages !== undefined, 'split']
+];
+export function impliedAction(args) {
+    return IMPLIED.find(([applies]) => applies(args))?.[1] ?? 'read';
+}
+function actionOf(args) {
+    const { action } = args;
+    if (action === undefined || action === null || action === '' || action === 'read') {
+        return impliedAction(args);
+    }
+    if (typeof action !== 'string') {
+        return { error: 'action must be a string' };
+    }
+    const name = action.trim().toLowerCase();
+    if (isAction(name)) {
+        return name;
+    }
+    return {
+        error: `unknown action "${action}"; actions are ${PDF_ACTIONS.join(', ')}, or leave action out to read a PDF`
+    };
+}
+export function pageSizeOf(value) {
+    if (typeof value !== 'string')
+        return undefined;
+    return PAGE_SIZES.find((size) => size.toLowerCase() === value.trim().toLowerCase());
+}
+export function quarterTurn(value) {
+    const degrees = Number(value);
+    if (!Number.isInteger(degrees)) {
+        return undefined;
+    }
+    const turn = ((degrees % 360) + 360) % 360;
+    return DEGREES.find((allowed) => allowed === turn);
+}
+function fieldValues(value) {
+    if (!isRecord(value) || Array.isArray(value))
+        return undefined;
+    const values = {};
+    for (const [name, entry] of Object.entries(value)) {
+        const ok = typeof entry === 'string' ||
+            typeof entry === 'number' ||
+            typeof entry === 'boolean' ||
+            (Array.isArray(entry) && entry.every((item) => typeof item === 'string'));
+        if (!ok) {
+            return undefined;
+        }
+        values[name] = entry;
+    }
+    return Object.keys(values).length ? values : undefined;
+}
+function permissionsOf(value) {
+    if (!isRecord(value))
+        return undefined;
+    const permissions = {};
+    for (const key of [
+        'print',
+        'modify',
+        'copy',
+        'annotate',
+        'fillForms',
+        'extract',
+        'assemble',
+        'printHighQuality'
+    ]) {
+        const allowed = value[key];
+        if (typeof allowed === 'boolean') {
+            permissions[key] = allowed;
+        }
+    }
+    return permissions;
+}
+function countError(action, count) {
+    if (action === 'create') {
+        return null;
+    }
+    if (!count) {
+        const create = action === 'read' ? ', or action "create" with markdown to make one' : '';
+        return `pass the attachmentId of a PDF (${WHERE_IDS_ARE})${create}`;
+    }
+    if (action === 'merge' && count < 2) {
+        return 'merge needs attachmentIds with at least two PDFs, in the order to join them';
+    }
+    if (action !== 'read' && action !== 'merge' && count > 1) {
+        return `${action} works on one PDF; pass a single attachmentId`;
+    }
+    return null;
+}
+function unquoted(markdown) {
+    const trimmed = markdown.trim();
+    if (!trimmed.startsWith('"') || !trimmed.endsWith('"')) {
+        return markdown;
+    }
+    try {
+        const inner = JSON.parse(trimmed);
+        return typeof inner === 'string' ? inner : markdown;
+    }
+    catch {
+        return markdown;
+    }
+}
+function createRequest(common, args) {
+    const written = textOf(args.markdown);
+    const markdown = written && unquoted(written);
+    if (!markdown) {
+        return { error: 'create needs markdown: the whole document as Markdown' };
+    }
+    const pageSize = pageSizeOf(args.pageSize);
+    if (args.pageSize !== undefined && !pageSize) {
+        return { error: `pageSize must be one of ${PAGE_SIZES.join(', ')}` };
+    }
+    return {
+        ...common,
+        action: 'create',
+        markdown,
+        pageSize,
+        landscape: args.landscape === true,
+        pageNumbers: args.pageNumbers === true
+    };
+}
+function watermarkRequest(common, args) {
+    const text = textOf(args.text);
+    if (!text) {
+        return { error: 'watermark needs text' };
+    }
+    const opacity = args.opacity === undefined ? undefined : Number(args.opacity);
+    if (opacity !== undefined && !(opacity >= 0 && opacity <= 1)) {
+        return { error: 'opacity must be between 0 and 1' };
+    }
+    const { position } = args;
+    if (position !== undefined && position !== 'over' && position !== 'under') {
+        return { error: 'position must be "over" or "under"' };
+    }
+    const pages = optionalPages(args.pages);
+    if (isError(pages)) {
+        return pages;
+    }
+    return { ...common, action: 'watermark', text, opacity, position, pages };
+}
+function pagedRequest(common, action, args) {
+    const pages = optionalPages(args.pages);
+    if (isError(pages)) {
+        return pages;
+    }
+    if (action === 'split') {
+        if (!pages) {
+            return { error: 'split needs pages: the page numbers to keep, counted from 1' };
+        }
+        return { ...common, action, pages };
+    }
+    const degrees = quarterTurn(args.degrees);
+    if (degrees === undefined) {
+        return { error: 'degrees must be 90, 180 or 270, clockwise' };
+    }
+    return { ...common, action, degrees, pages };
+}
+function actionRequest(action, common, args) {
+    switch (action) {
+        case 'create':
+            return createRequest(common, args);
+        case 'split':
+        case 'rotate':
+            return pagedRequest(common, action, args);
+        case 'watermark':
+            return watermarkRequest(common, args);
+        case 'fill': {
+            const values = fieldValues(args.values);
+            if (!values) {
+                return {
+                    error: 'fill needs values: { "field name": value } using the field names a read returns'
+                };
+            }
+            return { ...common, action, values };
+        }
+        case 'encrypt':
+            if (!common.password) {
+                return { error: 'encrypt needs password: the password the user chose' };
+            }
+            return {
+                ...common,
+                action,
+                ownerPassword: textOf(args.ownerPassword),
+                permissions: permissionsOf(args.permissions)
+            };
+        case 'decrypt':
+            if (!common.password) {
+                return { error: 'decrypt needs password: ask the user for it, never guess one' };
+            }
+            return { ...common, action };
+        default:
+            return { ...common, action };
+    }
+}
+function isError(value) {
+    return isRecord(value) && 'error' in value && typeof value.error === 'string';
+}
+export function parseRequest(args) {
+    const action = actionOf(args);
+    if (isError(action)) {
+        return action.error;
+    }
+    const ids = idsOf(args);
+    if (isError(ids)) {
+        return ids.error;
+    }
+    const counted = countError(action, ids.length);
+    if (counted) {
+        return counted;
+    }
+    if (args.password !== undefined && args.password !== null && !textOf(args.password)) {
+        return 'password must be a non-empty string';
+    }
+    if (args.output !== undefined && args.output !== null && !textOf(args.output)) {
+        return 'output must be a file name';
+    }
+    const output = textOf(args.output)?.trim();
+    const request = actionRequest(action, { ids, password: textOf(args.password), output }, args);
+    return isError(request) ? request.error : request;
+}

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

@@ -0,0 +1,6 @@
+import type { ToolDefinition } from '../contract/index.ts';
+import { type Pdfium, type Source } from './pdf/build.ts';
+import { type PdfRequest } from './pdf/request.ts';
+export { parsePages, parseRequest } from './pdf/request.ts';
+export declare function outputName(request: PdfRequest, inputs: readonly Source[]): string;
+export declare function createPdfTool(load?: () => Promise<Pdfium | null>): ToolDefinition;