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

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 './attachments/staging.js';
+import { checkOutputBytes, RUN_OUTPUT_BUDGET_BYTES } from './attachments/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/operations/compile.d.ts

@@ -1,7 +1,7 @@
-import type { ToolDefinition } from '../../capabilities/completion.ts';
+import type { ToolDefinition } from '../../contract/index.ts';
 import type { SkillCatalogEntry } from '../skills/catalog.ts';
 export interface CompileOperationToolsOptions {
-    httpRequestTool: ToolDefinition;
-    mcpCallTool?: ToolDefinition;
+    httpRequestTool?: ToolDefinition | undefined;
+    mcpCallTool?: ToolDefinition | undefined;
 }
 export declare function compileOperationTools(catalog: readonly SkillCatalogEntry[], { httpRequestTool, mcpCallTool }: CompileOperationToolsOptions): ToolDefinition[];

package/dist-lib/lib/tools/operations/compile.js

@@ -1,7 +1,7 @@
 import { z } from 'zod';
 import { BUILDERS, BUILDER_POLICY_VERSION } from './builders.js';
 import { createHash } from 'crypto';
-import { stableStringify } from '../../machine/index.js';
+import { stableStringify } from '../../helpers/stable-stringify.js';
 import { READ_METHODS } from '../http-methods.js';
 import { truncateResponseBody } from '../http-request/truncate-response.js';
 import { DECODERS } from './decoders.js';
@@ -36,6 +36,7 @@ function operationTool(owningSkill, operation, transportTool) {
         effect() {
             return read ? 'read' : 'write';
         },
+        egress: mcp ? () => operation.request.url : undefined,
         resource() {
             return hostOf(operation.request.url);
         },

package/dist-lib/lib/tools/operations/decoders.js

@@ -1,7 +1,7 @@
 import b4a from 'b4a';
 import { z } from 'zod';
 import { extractPageText } from '../../web-fetch/extract.js';
-import { decodeHtmlEntities } from '../../web-search/html-helpers.js';
+import { decodeHtmlEntities } from '../../helpers/html-helpers.js';
 import { ELISION } from '../http-request/truncate-response.js';
 export const DECODER_NAMES = ['gmail-message'];
 const KEPT_HEADERS = ['From', 'To', 'Subject', 'Date', 'Message-ID', 'References'];

package/dist-lib/lib/tools/operations/manifest.d.ts

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import type { ToolParameters } from '../../capabilities/completion.ts';
+import type { ToolParameters } from '../../contract/index.ts';
 declare const ResponseSchema: z.ZodUnion<readonly [z.ZodObject<{
     pick: z.ZodArray<z.ZodString>;
 }, z.core.$strict>, z.ZodObject<{

package/dist-lib/lib/tools/outbound-guard.d.ts

@@ -1,4 +1,5 @@
-import type { TrustedOrigin, TrustedSource, TrustedSourceFacts } from '../machine/index.ts';
+import type { OutboundGuard } from '../contract/index.ts';
+import type { TrustedOrigin, TrustedSource, TrustedSourceFacts } from '../contract/index.ts';
 export declare const REFUSAL = "Refusing to send:";
 export type { TrustedOrigin, TrustedSource };
 export interface GuardOptions {
@@ -11,3 +12,4 @@ export interface GuardFactOptions extends GuardOptions {
 export declare function trustedSourceFacts(origin: TrustedSourceFacts['origin'], text: string): TrustedSourceFacts;
 export declare function guardToolCall(toolName: string, args: Record<string, unknown>, options: GuardOptions): string | null;
 export declare function guardToolCallWithFacts(toolName: string, args: Record<string, unknown>, { sources, sourceFacts, externalWrite }: GuardFactOptions): string | null;
+export declare const outboundGuard: OutboundGuard;

package/dist-lib/lib/tools/outbound-guard.js

@@ -50,6 +50,10 @@ export function guardToolCallWithFacts(toolName, args, { sources, sourceFacts =
     }
     return invented(unverified, trusted);
 }
+export const outboundGuard = {
+    facts: trustedSourceFacts,
+    check: guardToolCallWithFacts
+};
 function lookalikeOf(value, trusted) {
     return grounded(value, trusted).failures[0]?.looksLike;
 }

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 {};