@qvac/harness 0.3.3 → 0.5.0

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

@@ -1,12 +1,14 @@
 import { z } from 'zod';
+import { errorMessage } from '../../guards.js';
 import { argvToObject, isObjectSchema, objectProps, walkCommands } from './cli-argv.js';
 export function buildSchemaAnnotation(schema) {
     const resourceEffects = schema['x-resource-effects'];
     return (argv) => {
         const first = argv[0];
         if (resourceEffects && typeof first === 'string') {
-            if (resourceEffects[basename(first)] === 'read')
+            if (resourceEffects[basename(first)] === 'read') {
                 return 'read';
+            }
         }
         return walkCommands(argv, schema).node['x-effect'] === 'read' ? 'read' : 'write';
     };
@@ -15,38 +17,46 @@ function basename(p) {
     return p.slice(Math.max(p.lastIndexOf('/'), p.lastIndexOf('\\')) + 1);
 }
 export function buildSchemaCheck(schema, resourcePaths) {
+    const source = schema;
     let zodSchema;
     try {
-        zodSchema = z.fromJSONSchema(schema);
+        zodSchema = z.fromJSONSchema(source);
     }
     catch (err) {
-        const msg = err instanceof Error ? err.message : String(err);
+        const msg = errorMessage(err);
         return () => `invalid skill cli JSON Schema: ${msg}`;
     }
     return (argv) => {
         const built = argvToObject(argv, schema);
-        if (typeof built === 'string')
+        if (typeof built === 'string') {
             return built;
+        }
         const cmdErr = assertSingleCommand(built, schema);
-        if (cmdErr)
+        if (cmdErr) {
             return cmdErr;
+        }
         const resourceErr = assertResourcePath(built, resourcePaths);
-        if (resourceErr)
+        if (resourceErr) {
             return resourceErr;
+        }
         const result = zodSchema.safeParse(built);
-        if (result.success)
+        if (result.success) {
             return null;
+        }
         return formatZod(result.error);
     };
 }
 function assertResourcePath(obj, resourcePaths) {
-    if (!resourcePaths || resourcePaths.length === 0 || typeof obj.script !== 'string')
+    if (!resourcePaths || resourcePaths.length === 0 || typeof obj.script !== 'string') {
         return null;
+    }
     return resourcePaths.includes(obj.script) ? null : 'script must be a bundled skill resource';
 }
 function assertSingleCommand(obj, schema) {
     const props = objectProps(schema);
-    const commandKeys = Object.keys(props).filter((k) => isObjectSchema(props[k]));
+    const commandKeys = Object.entries(props)
+        .filter(([, prop]) => isObjectSchema(prop))
+        .map(([k]) => k);
     const present = commandKeys.filter((k) => k in obj);
     if (present.length > 1) {
         return `only one command allowed (got ${present.join(', ')})`;
@@ -55,8 +65,9 @@ function assertSingleCommand(obj, schema) {
 }
 function formatZod(err) {
     const issue = err.issues[0];
-    if (!issue)
+    if (!issue) {
         return 'invalid parameters';
+    }
     const where = issue.path.length ? `${issue.path.join('.')}: ` : '';
     return `${where}${issue.message}`;
 }

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

@@ -1,5 +1,6 @@
 import fs from 'fs';
 import path from 'path';
+import { isRecord } from '../../guards.js';
 import { CLI_SCHEMA_FILENAME } from './cli-schema-types.js';
 export async function resolveCliSchema(skillDir, bin, readFile = (p) => fs.promises.readFile(p, 'utf8')) {
     const full = path.join(skillDir, CLI_SCHEMA_FILENAME);
@@ -8,27 +9,31 @@ export async function resolveCliSchema(skillDir, bin, readFile = (p) => fs.promi
         raw = await readFile(full);
     }
     catch (err) {
-        if (isEnoent(err))
+        if (isEnoent(err)) {
             return { bin };
+        }
         return { bin, schemaFile: CLI_SCHEMA_FILENAME };
     }
     try {
-        const parsed = JSON.parse(raw);
-        if (!isObj(parsed))
+        const schema = JSON.parse(raw);
+        if (!isSchemaObject(schema)) {
             return { bin, schemaFile: CLI_SCHEMA_FILENAME };
-        const schema = parsed;
-        if (!resourceGuardConsistent(schema))
+        }
+        if (!resourceGuardConsistent(schema)) {
             return { bin, schemaFile: CLI_SCHEMA_FILENAME };
-        if (!effectAnnotationsValid(schema))
+        }
+        if (!effectAnnotationsValid(schema)) {
             return { bin, schemaFile: CLI_SCHEMA_FILENAME };
-        if (!resourceEffectsValid(schema))
+        }
+        if (!resourceEffectsValid(schema)) {
             return { bin, schemaFile: CLI_SCHEMA_FILENAME };
+        }
         const resourcePaths = resolveResourcePaths(skillDir, schema);
         return {
             bin,
             schema,
             schemaFile: CLI_SCHEMA_FILENAME,
-            ...(resourcePaths.length ? { resourcePaths } : {})
+            resourcePaths: resourcePaths.length ? resourcePaths : undefined
         };
     }
     catch {
@@ -37,8 +42,9 @@ export async function resolveCliSchema(skillDir, bin, readFile = (p) => fs.promi
 }
 function resourceGuardConsistent(schema) {
     const resources = schema['x-resource-files'];
-    if (!resources || resources.length === 0)
+    if (!resources || resources.length === 0) {
         return true;
+    }
     return schema.properties?.script?.type === 'string';
 }
 function effectAnnotationsValid(schema) {
@@ -48,10 +54,12 @@ function effectAnnotationsValid(schema) {
 }
 function resourceEffectsValid(schema) {
     const effects = schema['x-resource-effects'];
-    if (effects === undefined)
+    if (effects === undefined) {
         return true;
-    if (typeof effects !== 'object' || effects === null || Array.isArray(effects))
+    }
+    if (typeof effects !== 'object' || effects === null || Array.isArray(effects)) {
         return false;
+    }
     const files = new Set(schema['x-resource-files'] ?? []);
     return Object.entries(effects).every(([file, effect]) => effect === 'read' && files.has(file));
 }
@@ -65,26 +73,26 @@ export function execBinFromTools(tools) {
     for (const entry of tools) {
         const m = /^exec\((.+)\)$/i.exec(entry.trim());
         const scope = m?.[1]?.trim();
-        if (scope)
+        if (scope) {
             return scope;
+        }
     }
     return undefined;
 }
 export async function loadSkillCli(skillDir, tools, readFile) {
     const bin = execBinFromTools(tools);
-    if (!bin)
+    if (!bin) {
         return undefined;
+    }
     const resolved = await resolveCliSchema(skillDir, bin, readFile);
-    if (resolved.schema || resolved.schemaFile)
+    if (resolved.schema || resolved.schemaFile) {
         return resolved;
+    }
     return undefined;
 }
 function isEnoent(err) {
-    return (typeof err === 'object' &&
-        err !== null &&
-        'code' in err &&
-        err.code === 'ENOENT');
+    return isRecord(err) && 'code' in err && err.code === 'ENOENT';
 }
-function isObj(v) {
-    return typeof v === 'object' && v !== null && !Array.isArray(v);
+function isSchemaObject(v) {
+    return isRecord(v) && !Array.isArray(v);
 }

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

@@ -1,4 +1,4 @@
-export type JsonSchema = {
+export interface JsonSchema {
     readonly type?: string;
     readonly properties?: Readonly<Record<string, JsonSchema>>;
     readonly required?: readonly string[];
@@ -14,17 +14,17 @@ export type JsonSchema = {
     readonly 'x-resource-effects'?: Readonly<Record<string, string>>;
     readonly 'x-effect'?: string;
     readonly [key: string]: unknown;
-};
-export type SkillCli = {
+}
+export interface SkillCli {
     readonly bin: string;
     readonly schema?: JsonSchema;
     readonly schemaFile?: string;
     readonly resourcePaths?: readonly string[];
-};
+}
 export declare const CLI_SCHEMA_FILENAME = "cli.schema.json";
-export type CliValidator = {
+export interface CliValidator {
     readonly bin: 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

@@ -27,8 +27,9 @@ export function checkCliOps(argv, compiled) {
     let lastErr = null;
     for (const c of compiled) {
         const err = c.check(argv);
-        if (err === null)
+        if (err === null) {
             return null;
+        }
         lastErr = err;
     }
     return lastErr ?? 'command does not match any allowed skill operation';

package/dist-lib/lib/tools/skills/credential-check.d.ts

@@ -2,19 +2,22 @@ import type { AbortSignal as BareAbortSignal } from 'bare-abort-controller';
 import { type CredentialStoreFn } from './auth-resolver.ts';
 import type { SkillCatalogEntry } from './catalog.ts';
 export declare const CREDENTIAL_CHECK_TTL_MS = 45000;
-type CredentialCheckResponse = {
+interface CredentialCheckResponse {
     readonly status: number;
     text?: () => Promise<string>;
-};
+}
 export type CredentialCheckFetch = (input: string, init: {
     method: string;
     headers: Headers;
     signal: BareAbortSignal;
 }) => Promise<CredentialCheckResponse>;
 export interface ValidateCredentialChecksOptions {
+    credentialStore?: CredentialStoreFn;
+    agentId?: string | null;
+    fetchImpl?: CredentialCheckFetch;
     refresh?: boolean | undefined;
     now?: () => number;
     ttlMs?: number;
 }
-export declare function validateCredentialChecks(catalog: readonly SkillCatalogEntry[], credentialStore: CredentialStoreFn | undefined, agentId?: string | null, fetchImpl?: CredentialCheckFetch, { refresh, now, ttlMs }?: ValidateCredentialChecksOptions): Promise<void>;
+export declare function validateCredentialChecks(catalog: readonly SkillCatalogEntry[], { credentialStore, agentId, fetchImpl, refresh, now, ttlMs }?: ValidateCredentialChecksOptions): Promise<void>;
 export {};

package/dist-lib/lib/tools/skills/credential-check.js

@@ -2,6 +2,7 @@ import fetch from '#fetch';
 import { Headers } from '#headers';
 import { AbortController } from 'bare-abort-controller';
 import { DEFAULT_USER_AGENT } from '../../user-agent.js';
+import { isRecord } from '../../guards.js';
 import { credentialRecord, isCredentialUrlAllowed } from './auth-resolver.js';
 import { credentialLastProbedAt, markCredentialRejected, markCredentialValid, setCredentialLastProbedAt } from './credential-health.js';
 const TIMEOUT_MS = 5_000;
@@ -10,7 +11,7 @@ const inflight = new Map();
 function scopedKey(key, agentId) {
     return agentId ? `${agentId}\0${key}` : key;
 }
-export async function validateCredentialChecks(catalog, credentialStore, agentId, fetchImpl, { refresh = false, now = Date.now, ttlMs = CREDENTIAL_CHECK_TTL_MS } = {}) {
+export async function validateCredentialChecks(catalog, { credentialStore, agentId, fetchImpl, refresh = false, now = Date.now, ttlMs = CREDENTIAL_CHECK_TTL_MS } = {}) {
     if (!credentialStore)
         return;
     const doFetch = fetchImpl ?? fetch;
@@ -19,16 +20,18 @@ export async function validateCredentialChecks(catalog, credentialStore, agentId
         for (const [key, check] of Object.entries(skill.requires?.credentialChecks ?? {})) {
             if (!isCredentialUrlAllowed(check.url, skill.allowList))
                 continue;
-            if (!checks.has(key))
+            if (!checks.has(key)) {
                 checks.set(key, { check, skill: skill.name });
+            }
         }
     }
     const at = now();
     await Promise.all([...checks].map(async ([key, { check, skill }]) => {
         if (!refresh) {
             const last = credentialLastProbedAt(key, agentId);
-            if (last !== undefined && at - last < ttlMs)
+            if (last !== undefined && at - last < ttlMs) {
                 return;
+            }
         }
         const sk = scopedKey(key, agentId);
         const pending = inflight.get(sk);
@@ -36,22 +39,28 @@ export async function validateCredentialChecks(catalog, credentialStore, agentId
             await pending;
             return;
         }
-        const probe = runCheck(key, check, skill, credentialStore, agentId, doFetch).finally(() => {
+        const probe = runCheck(key, check, {
+            skill,
+            credentialStore,
+            agentId,
+            fetchImpl: doFetch
+        }).finally(() => {
             inflight.delete(sk);
         });
         inflight.set(sk, probe);
         await probe;
-        setCredentialLastProbedAt(key, now(), agentId);
+        setCredentialLastProbedAt(key, now(), { agentId });
     }));
 }
-async function runCheck(key, check, skill, credentialStore, agentId, fetchImpl) {
+async function runCheck(key, check, { skill, credentialStore, agentId, fetchImpl }) {
     const record = credentialRecord(await credentialStore(key, { agentId, skills: [skill] }));
-    if (!record)
+    if (!record) {
         return;
+    }
     const controller = new AbortController();
     const timer = setTimeout(() => controller.abort('credential check timed out'), TIMEOUT_MS);
     try {
-        const headers = new Headers({ ...(check.headers ?? {}) });
+        const headers = new Headers(check.headers);
         if (!headers.has('user-agent')) {
             headers.set('user-agent', DEFAULT_USER_AGENT);
         }
@@ -76,15 +85,18 @@ async function runCheck(key, check, skill, credentialStore, agentId, fetchImpl)
     }
 }
 async function hasMcpAuthError(response) {
-    if (response.status < 200 || response.status >= 300 || !response.text)
+    if (response.status < 200 || response.status >= 300 || !response.text) {
         return false;
+    }
     try {
         const body = JSON.parse(await response.text());
-        const error = body.error;
-        if (!error)
+        const error = isRecord(body) ? body.error : undefined;
+        if (!isRecord(error)) {
             return false;
-        if (error.code === 401 || error.code === 403)
+        }
+        if (error.code === 401 || error.code === 403) {
             return true;
+        }
         return (typeof error.message === 'string' &&
             /unauthori[sz]ed|forbidden|token.*expired/i.test(error.message));
     }

package/dist-lib/lib/tools/skills/credential-grants.js

@@ -10,12 +10,7 @@ export function credentialGrants(catalog, skills) {
         if (!loaded.has(entry.name) || entry.allowList.length === 0)
             continue;
         for (const key of credentialSlots(entry).flat()) {
-            const list = map[key] ?? [];
-            for (const host of entry.allowList) {
-                if (!list.includes(host))
-                    list.push(host);
-            }
-            map[key] = list;
+            map[key] = [...new Set([...(map[key] ?? []), ...entry.allowList])];
         }
     }
     return map;

package/dist-lib/lib/tools/skills/credential-health.d.ts

@@ -3,6 +3,10 @@ export declare function markCredentialValid(key: string, agentId?: string | null
 export declare function recordCredentialHealth(key: string, status: number, agentId?: string | null): void;
 export declare function isCredentialRejected(key: string, agentId?: string | null, skill?: string | null): boolean;
 export declare function credentialLastProbedAt(key: string, agentId?: string | null, skill?: string | null): number | undefined;
-export declare function setCredentialLastProbedAt(key: string, at: number, agentId?: string | null, skill?: string | null): void;
+export interface CredentialScope {
+    readonly agentId?: string | null;
+    readonly skill?: string | null;
+}
+export declare function setCredentialLastProbedAt(key: string, at: number, { agentId, skill }?: CredentialScope): void;
 export declare function resetCredentialHealth(key: string, agentId?: string | null, skill?: string | null): void;
 export declare function resetAllCredentialHealth(): void;

package/dist-lib/lib/tools/skills/credential-health.js

@@ -10,8 +10,9 @@ export function markCredentialRejected(key, agentId, skill) {
 }
 export function markCredentialValid(key, agentId, skill) {
     rejected.delete(scopedKey(key, agentId, skill));
-    if (skill)
+    if (skill) {
         rejected.delete(scopedKey(key, agentId));
+    }
 }
 export function recordCredentialHealth(key, status, agentId) {
     if (status === 401 || status === 403) {
@@ -19,8 +20,9 @@ export function recordCredentialHealth(key, status, agentId) {
         markCredentialRejected(key, agentId);
     }
     else if (status < 400) {
-        if (isCredentialRejected(key, agentId))
+        if (isCredentialRejected(key, agentId)) {
             hlog('credential recovered', { key });
+        }
         markCredentialValid(key, agentId);
     }
 }
@@ -32,7 +34,7 @@ export function isCredentialRejected(key, agentId, skill) {
 export function credentialLastProbedAt(key, agentId, skill) {
     return lastProbedAt.get(scopedKey(key, agentId, skill));
 }
-export function setCredentialLastProbedAt(key, at, agentId, skill) {
+export function setCredentialLastProbedAt(key, at, { agentId, skill } = {}) {
     lastProbedAt.set(scopedKey(key, agentId, skill), at);
 }
 export function resetCredentialHealth(key, agentId, skill) {

package/dist-lib/lib/tools/skills/frontmatter-parser.js

@@ -1,12 +1,12 @@
 import { parseManifestBlock } from './manifest-parse.js';
 const FRONT_MATTER_RE = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/;
 const FIELD_RE = /^([A-Za-z_][\w-]*):(.*)$/;
-const LIST_FIELDS = new Set(['tools', 'platform', 'credentials', 'allow_list', 'aliases']);
 export function parseSkillFrontMatter(raw) {
     try {
         const match = FRONT_MATTER_RE.exec(raw);
-        if (!match)
+        if (!match) {
             return { meta: {}, body: raw };
+        }
         const block = match[1] ?? '';
         const meta = { ...parseFields(block), ...parseManifestBlock(block) };
         return { meta, body: (match[2] ?? '').trim() };
@@ -31,19 +31,24 @@ function parseFields(block) {
     const meta = {};
     for (const line of unwrap(block.split(/\r?\n/))) {
         const field = FIELD_RE.exec(line);
-        if (!field)
+        if (!field) {
             continue;
+        }
         const key = field[1] ?? '';
         const value = (field[2] ?? '').trim();
-        if (!value)
+        if (!value) {
             continue;
+        }
         if (key === 'allow_list') {
             meta.allowList = parseList(value);
         }
         else if (key === 'mcp_reads') {
             meta.mcpReads = parseList(value);
         }
-        else if (LIST_FIELDS.has(key)) {
+        else if (key === 'tools' ||
+            key === 'platform' ||
+            key === 'credentials' ||
+            key === 'aliases') {
             meta[key] = parseList(value);
         }
         else if (key === 'name' || key === 'description') {