@qvac/harness 0.7.0 → 1.0.0-rc.0

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

@@ -1,7 +1,9 @@
 import { z } from 'zod';
+import { BUILDERS, BUILDER_POLICY_VERSION } from './builders.js';
+import { createHash } from 'crypto';
+import { stableStringify } from '../../machine/index.js';
 import { READ_METHODS } from '../http-methods.js';
 import { truncateResponseBody } from '../http-request/truncate-response.js';
-import { BUILDERS } from './builders.js';
 import { DECODERS } from './decoders.js';
 export function compileOperationTools(catalog, { httpRequestTool, mcpCallTool }) {
     return catalog.flatMap((entry) => (entry.operations ?? []).flatMap((operation) => {
@@ -15,6 +17,14 @@ function operationTool(owningSkill, operation, transportTool) {
     const read = !mcp && READ_METHODS.has(operation.request.method);
     return {
         name: operation.tool,
+        policyVersion: createHash('sha256')
+            .update(stableStringify({
+            owningSkill,
+            operation,
+            builderVersion: BUILDER_POLICY_VERSION,
+            transportVersion: transportTool.policyVersion ?? null
+        }))
+            .digest('hex'),
         owningSkill,
         description: operation.description,
         parameters: operation.parameters,

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

@@ -4,6 +4,7 @@ import { DECODER_NAMES } from './decoders.js';
 const ParameterType = z.enum(['string', 'number', 'boolean', 'object', 'integer', 'array', 'null']);
 const ParameterSchema = z.lazy(() => z.object({
     type: z.union([ParameterType, z.array(ParameterType).min(1)]),
+    sensitive: z.literal(true).optional(),
     description: z.string().optional(),
     enum: z.array(z.string()).optional(),
     items: ParameterSchema.optional(),

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

@@ -1,11 +1,13 @@
+import type { TrustedOrigin, TrustedSource, TrustedSourceFacts } from '../machine/index.ts';
 export declare const REFUSAL = "Refusing to send:";
-export type TrustedOrigin = 'user' | 'tool-result' | 'skill';
-export interface TrustedSource {
-    origin: TrustedOrigin;
-    text: string;
-}
+export type { TrustedOrigin, TrustedSource };
 export interface GuardOptions {
     readonly sources: readonly TrustedSource[];
     externalWrite?: boolean;
 }
-export declare function guardToolCall(toolName: string, args: Record<string, unknown>, { sources, externalWrite }: GuardOptions): string | null;
+export interface GuardFactOptions extends GuardOptions {
+    readonly sourceFacts?: readonly TrustedSourceFacts[];
+}
+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;

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

@@ -9,7 +9,18 @@ const OUTBOUND_TOOLS = new Set(['http_request', 'mcp_call']);
 const MCP_READ_METHOD = /^(tools\/list|resources\/\w+|(get|list|search|read|find|fetch)[_.-])/i;
 const HINT_LIMIT = 5;
 export const REFUSAL = 'Refusing to send:';
-export function guardToolCall(toolName, args, { sources, externalWrite = false }) {
+export function trustedSourceFacts(origin, text) {
+    const addresses = text.includes('@') ? unique(text.match(ADDRESS) ?? []) : [];
+    return {
+        origin,
+        addresses,
+        refused: text.includes(REFUSAL)
+    };
+}
+export function guardToolCall(toolName, args, options) {
+    return guardToolCallWithFacts(toolName, args, options);
+}
+export function guardToolCallWithFacts(toolName, args, { sources, sourceFacts = [], externalWrite = false }) {
     if (!externalWrite && !isOutbound(toolName, args))
         return null;
     const addresses = unique(scanPayload(args));
@@ -20,15 +31,15 @@ export function guardToolCall(toolName, args, { sources, externalWrite = false }
     if (reserved) {
         return `${REFUSAL} ${mask(reserved)} is a reserved documentation domain (RFC 2606) that cannot receive mail — a placeholder copied from an example, not a real address. Ask the user for the actual address.`;
     }
-    const trusted = addressesIn(sources, (origin) => origin !== 'skill');
+    const trusted = addressesIn(sources, sourceFacts, (origin) => origin !== 'skill');
     const unverified = addresses.filter((value) => !grounded(value, trusted).ok);
     if (!unverified.length) {
         return null;
     }
-    if (alreadyRefusedThisTurn(sources)) {
+    if (alreadyRefusedThisTurn(sources, sourceFacts)) {
         return `${REFUSAL} ${masked(unverified)} still cannot be verified, and an earlier call in this turn was already refused for the same reason. Stop calling this tool. Reply to the user in plain text and ask them for the address.`;
     }
-    const fromSkill = addressesIn(sources, (origin) => origin === 'skill');
+    const fromSkill = addressesIn(sources, sourceFacts, (origin) => origin === 'skill');
     const placeholders = unverified.filter((value) => grounded(value, fromSkill).ok);
     if (placeholders.length) {
         return `${REFUSAL} ${masked(placeholders)} appears only in the skill's own documentation — an example placeholder, not a real address. Ask the user for the actual address.`;
@@ -53,16 +64,17 @@ function invented(unverified, trusted) {
     }
     return `${base} Addresses that do appear: ${trusted.slice(0, HINT_LIMIT).join(', ')}. Use one of those if it is the intended target; otherwise ask the user instead of retrying.`;
 }
-function alreadyRefusedThisTurn(sources) {
+function alreadyRefusedThisTurn(sources, sourceFacts) {
     let turnStart = 0;
     for (const [index, source] of sources.entries()) {
         if (source.origin === 'user') {
             turnStart = index + 1;
         }
     }
-    return sources
+    return (sources
         .slice(turnStart)
-        .some((source) => source.origin === 'tool-result' && source.text.includes(REFUSAL));
+        .some((source) => source.origin === 'tool-result' && source.text.includes(REFUSAL)) ||
+        sourceFacts.some((source) => source.origin === 'tool-result' && source.refused));
 }
 function isOutbound(toolName, args) {
     if (!OUTBOUND_TOOLS.has(toolName))
@@ -100,13 +112,18 @@ function decodeEncoded(value) {
         return null;
     }
 }
-function addressesIn(sources, accept) {
+function addressesIn(sources, sourceFacts, accept) {
     const found = [];
     for (const source of sources) {
         if (!accept(source.origin))
             continue;
         found.push(...(source.text.match(ADDRESS) ?? []));
     }
+    for (const source of sourceFacts) {
+        if (!accept(source.origin))
+            continue;
+        found.push(...source.addresses);
+    }
     return unique(found);
 }
 function unique(values) {

package/dist-lib/lib/tools/skills/catalog.d.ts

@@ -10,6 +10,7 @@ import type { CapabilityProfile } from '../../models/model-catalog.ts';
 export interface SkillCatalogEntry {
     name: string;
     description: string;
+    contentDigest?: string;
     aliases?: string[];
     preloadOnName?: boolean;
     tools: string[];

package/dist-lib/lib/tools/skills/catalog.js

@@ -1,6 +1,8 @@
 import fs from 'fs';
+import { createHash } from 'crypto';
 import { platform } from 'os';
 import path from 'path';
+import { errorCode } from '../../guards.js';
 import { parseSkillFrontMatter } from './frontmatter-parser.js';
 import { buildCliValidator, loadSkillCli } from './cli-schema.js';
 import { isModelCompatible, isStub, isToolSupported, resolveSkillState, SKILL_STATE, supportsPlatform } from './skill-state.js';
@@ -79,6 +81,9 @@ function mergeOverlay(base, overlay) {
     const { origin: _origin, mcpReads: _mcpReads, operations: _operations, ...rest } = overlay;
     return {
         ...rest,
+        contentDigest: createHash('sha256')
+            .update(`${base.contentDigest ?? ''}:${overlay.contentDigest ?? ''}`)
+            .digest('hex'),
         credentials: base.credentials,
         allowList: base.allowList,
         platform: base.platform,
@@ -151,11 +156,18 @@ async function loadEntry(skillsDir, dir, origin) {
         const tools = meta.tools ?? [];
         const cli = await loadSkillCli(skillDir, tools);
         const referenceFiles = await loadReferenceFiles(skillDir);
+        const contentHash = createHash('sha256').update(raw);
+        for (const file of referenceFiles) {
+            contentHash.update(file);
+            contentHash.update(await fs.promises.readFile(path.join(skillDir, file)));
+        }
+        await hashSkillScripts(path.join(skillDir, 'scripts'), contentHash);
         const operations = origin === 'overlay' ? [] : await loadOperations(skillDir, dir);
         const platform = platformsOf(meta.platform, origin);
         return {
             name: dir,
             description: meta.description ?? '',
+            contentDigest: contentHash.digest('hex'),
             aliases: meta.aliases,
             preloadOnName: meta.preloadOnName === false ? false : undefined,
             tools,
@@ -194,6 +206,29 @@ async function loadOperations(skillDir, name) {
     }
     return operations;
 }
+async function hashSkillScripts(directory, hash, prefix = 'scripts') {
+    let entries;
+    try {
+        entries = await fs.promises.readdir(directory, { withFileTypes: true });
+    }
+    catch (error) {
+        if (errorCode(error) === 'ENOENT') {
+            return;
+        }
+        throw error;
+    }
+    for (const entry of entries.sort((left, right) => left.name.localeCompare(right.name))) {
+        const file = path.join(directory, entry.name);
+        const relative = `${prefix}/${entry.name}`;
+        if (entry.isDirectory()) {
+            await hashSkillScripts(file, hash, relative);
+        }
+        else if (entry.isFile() && entry.name.endsWith('.py')) {
+            hash.update(relative);
+            hash.update(await fs.promises.readFile(file));
+        }
+    }
+}
 async function loadReferenceFiles(skillDir) {
     try {
         const entries = await fs.promises.readdir(path.join(skillDir, 'references'));

package/dist-lib/lib/tools/skills/cli-schema-types.d.ts

@@ -24,6 +24,7 @@ export interface SkillCli {
 export declare const CLI_SCHEMA_FILENAME = "cli.schema.json";
 export interface CliValidator {
     readonly bin: string;
+    readonly fingerprint: string;
     readonly check: (argv: readonly string[]) => string | null;
     readonly annotation: (argv: readonly string[]) => 'read' | 'write';
     readonly effect: (argv: readonly string[]) => 'read' | 'write';

package/dist-lib/lib/tools/skills/cli-schema.js

@@ -2,11 +2,35 @@ export { CLI_SCHEMA_FILENAME } from './cli-schema-types.js';
 export { argvToObject } from './cli-argv.js';
 export { loadSkillCli, resolveCliSchema, execBinFromTools } from './cli-schema-load.js';
 import { buildSchemaAnnotation, buildSchemaCheck } from './cli-schema-check.js';
+import { createHash } from 'crypto';
+import fs from 'fs';
+import { errorCode } from '../../guards.js';
+import { stableStringify } from '../../machine/index.js';
+const CLI_POLICY_VERSION = 1;
+function resourceIdentity(resourcePath) {
+    try {
+        const digest = createHash('sha256').update(fs.readFileSync(resourcePath)).digest('hex');
+        return [resourcePath, digest];
+    }
+    catch (error) {
+        const code = errorCode(error) ?? 'unreadable';
+        return [resourcePath, `unreadable:${code}`];
+    }
+}
 export function buildCliValidator(def) {
     const bin = def.bin.toLowerCase();
+    const fingerprint = createHash('sha256')
+        .update(stableStringify({
+        version: CLI_POLICY_VERSION,
+        bin,
+        schema: def.schema ?? null,
+        resources: (def.resourcePaths ?? []).map(resourceIdentity)
+    }))
+        .digest('hex');
     if (!def.schema) {
         return {
             bin,
+            fingerprint,
             check: () => 'skill cli schema is missing',
             annotation: () => 'write',
             effect: () => 'write'
@@ -16,6 +40,7 @@ export function buildCliValidator(def) {
     const annotation = buildSchemaAnnotation(def.schema);
     return {
         bin,
+        fingerprint,
         check,
         annotation,
         effect: (argv) => (check(argv) === null ? annotation(argv) : 'write')

package/dist-lib/lib/wire.d.ts

@@ -1,5 +1,8 @@
 import type { HarnessEvent } from './contract-types.ts';
 export interface WireEvent {
+    runId?: string | null;
+    round?: number | null;
+    replacedTypes?: string[] | null;
     type: string;
     text?: string | null;
     name?: string | null;
@@ -40,6 +43,8 @@ export interface WireDownloadEvent {
     assetId?: string | null;
     message?: string | null;
 }
+export declare function isPlainWireValue(value: unknown): boolean;
+export declare function redactedRecoveryFields(source: Record<string, unknown>): Record<string, unknown>;
 export declare function toWire(event: HarnessEvent): WireEvent;
 export declare function fromWire(event: WireEvent): HarnessEvent;
 export declare function toDownloadWire(event: HarnessEvent): WireDownloadEvent;

package/dist-lib/lib/wire.js

@@ -3,14 +3,66 @@ import { isRecord } from './guards.js';
 function stringField(value) {
     return typeof value === 'string' ? value : undefined;
 }
+function isRunVersion(value) {
+    return (typeof value === 'string' &&
+        value.length <= 40 &&
+        /^\d{1,10}(?:\.\d{1,10}){0,3}(?:-[A-Za-z0-9.-]{1,16})?$/.test(value));
+}
 function objectField(value) {
     return isRecord(value) ? value : {};
 }
+export function isPlainWireValue(value) {
+    if (value === null)
+        return true;
+    if (typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean') {
+        return true;
+    }
+    return (Array.isArray(value) &&
+        value.every((item) => typeof item === 'string' || typeof item === 'number' || typeof item === 'boolean'));
+}
 function isResource(value) {
     return isRecord(value) && typeof value.kind === 'string' && typeof value.label === 'string';
 }
+const REDACTED_RECOVERY_KEYS = new Set(['forkAt', 'forkSafe', 'recoveryOperationIds']);
+export function redactedRecoveryFields(source) {
+    const fields = {};
+    for (const [key, value] of Object.entries(source)) {
+        if (!REDACTED_RECOVERY_KEYS.has(key))
+            continue;
+        if (isPlainWireValue(value)) {
+            fields[key] = value;
+        }
+    }
+    return fields;
+}
 export function toWire(event) {
+    const wire = toWirePayload(event);
+    if (typeof event.runId === 'string') {
+        wire.runId = event.runId;
+    }
+    if (typeof event.round === 'number') {
+        wire.round = event.round;
+    }
+    if (typeof event.callId === 'string') {
+        wire.callId = event.callId;
+    }
+    return wire;
+}
+function toWirePayload(event) {
     switch (event.type) {
+        case 'run-started':
+        case 'run-resumed':
+        case 'paused':
+            return { type: event.type };
+        case 'round-reset': {
+            const wire = { type: event.type };
+            if (Array.isArray(event.replacedTypes)) {
+                wire.replacedTypes = event.replacedTypes.filter((value) => typeof value === 'string');
+            }
+            return wire;
+        }
+        case 'recovery-required':
+            return { type: event.type, payload: event.operation };
         case 'content':
         case 'thinking':
             return { type: event.type, text: event.text };
@@ -39,7 +91,7 @@ export function toWire(event) {
                 decision: stringField(event.decision)
             };
         case 'metrics': {
-            const { type, ...metrics } = event;
+            const { type, runId, ...metrics } = event;
             return { type, metrics };
         }
         case 'inference-call':
@@ -56,8 +108,29 @@ export function toWire(event) {
                     reason: event.reason
                 }
             };
-        case 'error':
-            return { type: 'error', message: event.message };
+        case 'error': {
+            const diagnostic = {};
+            if (event.code === 'PENDING_ARGS_REDACTED') {
+                diagnostic.code = event.code;
+                Object.assign(diagnostic, redactedRecoveryFields(event));
+            }
+            if (event.name === 'RunIncompatible' &&
+                (event.kind === 'machine' || event.kind === 'log' || event.kind === 'xstate') &&
+                isRunVersion(event.found) &&
+                isRunVersion(event.expected)) {
+                diagnostic.kind = event.kind;
+                diagnostic.found = event.found;
+                diagnostic.expected = event.expected;
+            }
+            const wire = { type: 'error', message: event.message };
+            if (typeof event.name === 'string') {
+                wire.name = event.name;
+            }
+            if (Object.keys(diagnostic).length > 0) {
+                wire.payload = diagnostic;
+            }
+            return wire;
+        }
         case 'aborted':
             return { type: 'aborted' };
         default:
@@ -65,7 +138,34 @@ export function toWire(event) {
     }
 }
 export function fromWire(event) {
+    const decoded = fromWirePayload(event);
+    if (event.runId) {
+        decoded.runId = event.runId;
+    }
+    if (event.runId &&
+        event.round !== null &&
+        event.round !== undefined &&
+        ['content', 'thinking', 'tool-call', 'tool-result', 'tool-activity', 'round-reset'].includes(event.type)) {
+        decoded.round = event.round;
+    }
+    if (event.callId) {
+        decoded.callId = event.callId;
+    }
+    return decoded;
+}
+function fromWirePayload(event) {
     switch (event.type) {
+        case 'run-started':
+        case 'run-resumed':
+        case 'paused':
+            return { type: event.type };
+        case 'round-reset':
+            return {
+                type: event.type,
+                replacedTypes: event.replacedTypes ?? undefined
+            };
+        case 'recovery-required':
+            return { type: event.type, operation: event.payload };
         case 'content':
         case 'thinking':
             return { type: event.type, text: event.text ?? '' };
@@ -109,8 +209,31 @@ export function fromWire(event) {
                 reason: sent.reason || undefined
             };
         }
-        case 'error':
-            return { type: 'error', message: event.message ?? 'harness error' };
+        case 'error': {
+            const diagnostic = objectField(event.payload);
+            const decoded = {
+                type: 'error',
+                message: event.message ?? 'harness error'
+            };
+            if (event.name) {
+                decoded.name = event.name;
+            }
+            if (diagnostic.code === 'PENDING_ARGS_REDACTED') {
+                decoded.code = diagnostic.code;
+                Object.assign(decoded, redactedRecoveryFields(diagnostic));
+            }
+            if (event.name === 'RunIncompatible' &&
+                (diagnostic.kind === 'machine' ||
+                    diagnostic.kind === 'log' ||
+                    diagnostic.kind === 'xstate') &&
+                isRunVersion(diagnostic.found) &&
+                isRunVersion(diagnostic.expected)) {
+                decoded.kind = diagnostic.kind;
+                decoded.found = diagnostic.found;
+                decoded.expected = diagnostic.expected;
+            }
+            return decoded;
+        }
         case 'aborted':
             return { type: 'aborted' };
         default:

package/dist-lib/schema/harness.js

@@ -70,7 +70,9 @@ export function registerHarnessTypes(ns) {
             'rag-result',
             'question-result',
             'drive-result',
-            'invoke'
+            'invoke',
+            'run-log-result',
+            'pause'
         ],
         strings: true
     });
@@ -113,7 +115,8 @@ export function registerHarnessTypes(ns) {
             { name: 'captureInferenceCalls', type: 'bool' },
             { name: 'capability', type: 'string' },
             { name: 'arguments', type: 'json' },
-            { name: 'enhance', type: 'string' }
+            { name: 'enhance', type: 'string' },
+            { name: 'runId', type: 'string' }
         ]
     });
     ns.register({
@@ -136,7 +139,13 @@ export function registerHarnessTypes(ns) {
             'tool-activity',
             'drive-ask',
             'inference-call',
-            'inference-sent'
+            'inference-sent',
+            'run-started',
+            'run-resumed',
+            'paused',
+            'recovery-required',
+            'round-reset',
+            'run-log-append'
         ],
         strings: true
     });
@@ -170,7 +179,10 @@ export function registerHarnessTypes(ns) {
             { name: 'payload', type: 'json' },
             { name: 'intent', type: 'string' },
             { name: 'display', type: 'json' },
-            { name: 'rawCall', type: 'string' }
+            { name: 'rawCall', type: 'string' },
+            { name: 'runId', type: 'string' },
+            { name: 'round', type: 'uint' },
+            { name: 'replacedTypes', type: 'string', array: true }
         ]
     });
     ns.register({
@@ -339,7 +351,8 @@ export function registerHarnessTypes(ns) {
             { name: 'supportsImages', type: 'bool', required: true },
             { name: 'expectedSize', type: 'uint', required: true },
             { name: 'actualSize', type: 'uint' },
-            { name: 'label', type: 'string' }
+            { name: 'label', type: 'string' },
+            { name: 'isLoading', type: 'bool' }
         ]
     });
     ns.register({
@@ -451,7 +464,10 @@ export function registerHarnessTypes(ns) {
             { name: 'capabilityProfile', type: '@harness/capability-profile', required: true },
             { name: 'recommendedModelName', type: 'string', required: true },
             { name: 'memoryBudget', type: '@harness/memory-budget' },
-            { name: 'mobile', type: 'bool' }
+            { name: 'mobile', type: 'bool' },
+            { name: 'completionRecovery', type: 'bool' },
+            { name: 'hostRunLog', type: 'bool' },
+            { name: 'hostRunLogVersion', type: 'uint' }
         ]
     });
     ns.register({