@qvac/harness 0.7.2 → 0.8.0

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

@@ -0,0 +1,82 @@
+import b4a from 'b4a';
+import { stageInputs } from '../exec/adapters/python/attachments.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 '../capabilities/completion.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;