@holdyourvoice/hyv 3.3.5 → 3.4.1

package/dist/agents/load.js

@@ -0,0 +1,184 @@
+import { readFileSync, readdirSync, lstatSync } from 'node:fs';
+import { join, resolve, isAbsolute } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { AGENT_SCHEMA_VERSION, VALID_PERMISSIONS, VALID_UNAVAILABLE_STATUSES, } from './types.js';
+const MAX_MANIFEST_BYTES = 1 << 20;
+export const SKILLS_DIRECTORY = 'skills';
+const PACKAGE_ROOT = fileURLToPath(new URL('../../', import.meta.url));
+const DESCRIPTOR_KEYS = new Set(['schema_version', 'id', 'title', 'description', 'instruction_file', 'role', 'workflow_phase', 'input', 'output', 'evidence_requirements', 'permissions', 'stop_conditions', 'tool_free_mode', 'handoff_to']);
+const IO_KEYS = new Set(['required', 'optional']);
+const TOOL_FREE_MODE_KEYS = new Set(['available', 'behavior', 'unavailable_statuses']);
+function isAgentDirectory(name) {
+    return name.startsWith('hyv-') && !name.startsWith('hyv-mcpb');
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function hasOnlyKeys(value, keys) {
+    return Object.keys(value).every((key) => keys.has(key));
+}
+function stringArray(value) {
+    return Array.isArray(value) && value.every((entry) => typeof entry === 'string' && entry.length > 0);
+}
+function validIO(value) {
+    return isRecord(value) && hasOnlyKeys(value, IO_KEYS) && stringArray(value.required) && stringArray(value.optional) && value.required.length > 0;
+}
+function validToolFreeMode(value) {
+    return isRecord(value)
+        && hasOnlyKeys(value, TOOL_FREE_MODE_KEYS)
+        && value.available === true
+        && typeof value.behavior === 'string' && value.behavior.length > 0
+        && stringArray(value.unavailable_statuses) && value.unavailable_statuses.length > 0
+        && value.unavailable_statuses.every((status) => VALID_UNAVAILABLE_STATUSES.has(status));
+}
+function validateDescriptor(value) {
+    if (!isRecord(value) || !hasOnlyKeys(value, DESCRIPTOR_KEYS))
+        return 'manifest must contain only the supported contract fields';
+    const descriptor = value;
+    if (descriptor.schema_version !== AGENT_SCHEMA_VERSION)
+        return `unsupported schema_version "${descriptor.schema_version}"`;
+    if (![descriptor.id, descriptor.title, descriptor.description, descriptor.instruction_file, descriptor.role, descriptor.workflow_phase].every((value) => typeof value === 'string' && value.length > 0)) {
+        return 'id, title, description, role, and workflow_phase are required';
+    }
+    if (descriptor.instruction_file !== 'SKILL.md')
+        return 'instruction_file must be SKILL.md';
+    if (!validIO(descriptor.input) || !validIO(descriptor.output)) {
+        return 'input and output require at least one entry in required';
+    }
+    if (!stringArray(descriptor.evidence_requirements) || !stringArray(descriptor.stop_conditions) || !stringArray(descriptor.permissions) || !stringArray(descriptor.handoff_to)) {
+        return 'evidence_requirements and stop_conditions require at least one entry';
+    }
+    if (!descriptor.evidence_requirements.length || !descriptor.stop_conditions.length)
+        return 'evidence_requirements and stop_conditions require at least one entry';
+    for (const permission of descriptor.permissions) {
+        if (!VALID_PERMISSIONS.has(permission))
+            return `unsupported permission "${permission}"`;
+    }
+    if (!validToolFreeMode(descriptor.tool_free_mode)) {
+        return 'tool_free_mode requires available and behavior';
+    }
+    return undefined;
+}
+function validOpenAiInterface(value) {
+    const lines = value.trimEnd().split('\n');
+    const quotedString = (line, prefix) => {
+        if (!line?.startsWith(prefix))
+            return false;
+        try {
+            const parsed = JSON.parse(line.slice(prefix.length));
+            return typeof parsed === 'string' && parsed.length > 0;
+        }
+        catch {
+            return false;
+        }
+    };
+    return lines.length === 4
+        && lines[0] === 'interface:'
+        && quotedString(lines[1], '  display_name: ')
+        && quotedString(lines[2], '  short_description: ')
+        && quotedString(lines[3], '  default_prompt: ');
+}
+function loadPackage(directory) {
+    const manifestPath = join(directory, 'agent.json');
+    const stat = lstatSync(manifestPath);
+    if (stat.isSymbolicLink() || !stat.isFile())
+        throw new Error(`inspect manifest: ${manifestPath} must be a regular file`);
+    if (stat.size > MAX_MANIFEST_BYTES)
+        throw new Error(`inspect manifest: ${manifestPath} exceeds ${MAX_MANIFEST_BYTES} bytes`);
+    const raw = readFileSync(manifestPath, 'utf8');
+    if (Buffer.byteLength(raw, 'utf8') > MAX_MANIFEST_BYTES)
+        throw new Error(`inspect manifest: ${manifestPath} exceeds ${MAX_MANIFEST_BYTES} bytes`);
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new Error(`parse manifest: ${manifestPath} is not valid JSON`);
+    }
+    const error = validateDescriptor(parsed);
+    if (error)
+        throw new Error(`validate manifest: ${manifestPath}: ${error}`);
+    const descriptor = parsed;
+    const instructionPath = join(directory, descriptor.instruction_file);
+    const instructionStat = lstatSync(instructionPath);
+    if (instructionStat.isSymbolicLink() || !instructionStat.isFile()) {
+        throw new Error(`inspect instructions: ${instructionPath} must be a regular file`);
+    }
+    const instructions = readFileSync(instructionPath, 'utf8');
+    const interfacePath = join(directory, 'agents', 'openai.yaml');
+    const interfaceStat = lstatSync(interfacePath);
+    if (interfaceStat.isSymbolicLink() || !interfaceStat.isFile() || interfaceStat.size > MAX_MANIFEST_BYTES) {
+        throw new Error(`inspect OpenAI interface: ${interfacePath} must be a regular file within ${MAX_MANIFEST_BYTES} bytes`);
+    }
+    const openai = readFileSync(interfacePath, 'utf8');
+    if (Buffer.byteLength(openai, 'utf8') > MAX_MANIFEST_BYTES || !validOpenAiInterface(openai)) {
+        throw new Error(`validate OpenAI interface: ${interfacePath} must contain the supported interface metadata`);
+    }
+    return { descriptor, directory, instructions };
+}
+function locateSkillsRoot(start) {
+    let current = start;
+    for (;;) {
+        const candidate = join(current, SKILLS_DIRECTORY);
+        try {
+            const stat = lstatSync(candidate);
+            if (stat.isDirectory() && !stat.isSymbolicLink())
+                return candidate;
+        }
+        catch {
+            // continue upward
+        }
+        const parent = resolve(current, '..');
+        if (parent === current)
+            break;
+        current = parent;
+    }
+    throw new Error(`locate HYV package root: no ${SKILLS_DIRECTORY} directory found from ${start}`);
+}
+export function loadAllFrom(root) {
+    const skillsRoot = locateSkillsRoot(root);
+    const entries = readdirSync(skillsRoot, { withFileTypes: true });
+    const packages = new Map();
+    for (const entry of entries) {
+        if (!entry.isDirectory() || !isAgentDirectory(entry.name))
+            continue;
+        const loaded = loadPackage(join(skillsRoot, entry.name));
+        if (loaded.descriptor.id !== entry.name) {
+            throw new Error(`load ${entry.name}: id must match skill directory`);
+        }
+        if (packages.has(loaded.descriptor.id))
+            throw new Error(`duplicate agent id "${loaded.descriptor.id}"`);
+        packages.set(loaded.descriptor.id, loaded);
+    }
+    for (const loaded of packages.values()) {
+        for (const target of loaded.descriptor.handoff_to) {
+            if (!packages.has(target))
+                throw new Error(`agent "${loaded.descriptor.id}" hands off to unknown agent "${target}"`);
+        }
+    }
+    return packages;
+}
+export function loadAll(start = PACKAGE_ROOT) {
+    return loadAllFrom(start);
+}
+export function sortedIds(packages) {
+    return [...packages.keys()].sort();
+}
+export function validateAll(packages) {
+    for (const loaded of packages.values()) {
+        const error = validateDescriptor(loaded.descriptor);
+        if (error)
+            throw new Error(`validate manifest: ${loaded.directory}: ${error}`);
+        for (const target of loaded.descriptor.handoff_to) {
+            if (!packages.has(target))
+                throw new Error(`agent "${loaded.descriptor.id}" hands off to unknown agent "${target}"`);
+        }
+    }
+}
+export function validateId(packages, id) {
+    if (!packages.has(id))
+        throw new Error(`unknown agent "${id}"`);
+}
+export function isAbsolutePath(value) {
+    return isAbsolute(value);
+}

package/dist/agents/load.test.js

@@ -0,0 +1,149 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { loadAll, loadAllFrom, validateAll, validateId, sortedIds } from './load.js';
+import { AGENT_SCHEMA_VERSION } from './types.js';
+function makePackage(dir, id, overrides = {}) {
+    const packageDir = join(dir, 'skills', id);
+    mkdirSync(join(packageDir, 'agents'), { recursive: true });
+    const descriptor = {
+        schema_version: AGENT_SCHEMA_VERSION,
+        id,
+        title: id,
+        description: 'test agent',
+        instruction_file: 'SKILL.md',
+        role: 'Tester',
+        workflow_phase: 'test',
+        input: { required: ['draft'], optional: [] },
+        output: { required: ['report'], optional: [] },
+        evidence_requirements: ['preserve evidence'],
+        permissions: ['read_repository'],
+        stop_conditions: ['stop when evidence missing'],
+        tool_free_mode: {
+            available: true,
+            behavior: 'report NOT_AVAILABLE',
+            unavailable_statuses: ['NOT_AVAILABLE', 'NOT_RUN'],
+        },
+        handoff_to: [],
+        ...overrides,
+    };
+    writeFileSync(join(packageDir, 'agent.json'), JSON.stringify(descriptor));
+    writeFileSync(join(packageDir, 'SKILL.md'), `# ${id}\n\nUsage: hyv ${id} draft.md\n`);
+    writeFileSync(join(packageDir, 'agents', 'openai.yaml'), `interface:\n  display_name: "${id}"\n  short_description: "test agent"\n  default_prompt: "Use ${id}"\n`);
+    return packageDir;
+}
+function makeTempRoot() {
+    return mkdtempSync(join(tmpdir(), 'hyv-agents-'));
+}
+test('loads all valid packages and rejects unknown schema version', () => {
+    const root = makeTempRoot();
+    try {
+        const first = makePackage(root, 'hyv-alpha');
+        makePackage(root, 'hyv-beta', { handoff_to: ['hyv-alpha'] });
+        const packages = loadAllFrom(root);
+        assert.deepEqual(sortedIds(packages), ['hyv-alpha', 'hyv-beta']);
+        assert.equal(packages.get('hyv-alpha').directory, first);
+        assert.match(packages.get('hyv-alpha').instructions, /^# hyv-alpha/);
+    }
+    finally {
+        rmSync(root, { recursive: true, force: true });
+    }
+});
+test('rejects a package whose id does not match its directory name', () => {
+    const root = makeTempRoot();
+    try {
+        makePackage(root, 'hyv-alpha', { id: 'hyv-mismatch' });
+        assert.throws(() => loadAllFrom(root), /id must match skill directory/);
+    }
+    finally {
+        rmSync(root, { recursive: true, force: true });
+    }
+});
+test('rejects a handoff target that does not exist', () => {
+    const root = makeTempRoot();
+    try {
+        makePackage(root, 'hyv-alpha', { handoff_to: ['hyv-ghost'] });
+        assert.throws(() => loadAllFrom(root), /hands off to unknown agent/);
+    }
+    finally {
+        rmSync(root, { recursive: true, force: true });
+    }
+});
+test('rejects an unsupported permission and an unsupported status', () => {
+    const root = makeTempRoot();
+    try {
+        makePackage(root, 'hyv-alpha', { permissions: ['definitely-not-real'] });
+        assert.throws(() => loadAllFrom(root), /unsupported permission/);
+        rmSync(root, { recursive: true, force: true });
+        const root2 = makeTempRoot();
+        makePackage(root2, 'hyv-beta', {
+            tool_free_mode: { available: true, behavior: 'x', unavailable_statuses: ['NOPE'] },
+        });
+        assert.throws(() => loadAllFrom(root2), /tool_free_mode requires/);
+    }
+    finally {
+        rmSync(root, { recursive: true, force: true });
+    }
+});
+test('validateAll and validateId report PASS or unknown id', () => {
+    const root = makeTempRoot();
+    try {
+        makePackage(root, 'hyv-alpha');
+        const packages = loadAllFrom(root);
+        validateAll(packages);
+        validateId(packages, 'hyv-alpha');
+        assert.throws(() => validateId(packages, 'hyv-missing'), /unknown agent/);
+    }
+    finally {
+        rmSync(root, { recursive: true, force: true });
+    }
+});
+test('rejects a malformed agent.json', () => {
+    const root = makeTempRoot();
+    try {
+        const packageDir = join(root, 'skills', 'hyv-alpha');
+        mkdirSync(join(packageDir, 'agents'), { recursive: true });
+        writeFileSync(join(packageDir, 'agent.json'), '{ not json');
+        writeFileSync(join(packageDir, 'SKILL.md'), '# x');
+        assert.throws(() => loadAllFrom(root), /not valid JSON/);
+    }
+    finally {
+        rmSync(root, { recursive: true, force: true });
+    }
+});
+test('rejects unknown contract fields and invalid OpenAI interface metadata', () => {
+    const root = makeTempRoot();
+    try {
+        makePackage(root, 'hyv-alpha', { unsupported: true });
+        assert.throws(() => loadAllFrom(root), /supported contract fields/);
+        rmSync(root, { recursive: true, force: true });
+        const root2 = makeTempRoot();
+        const packageDir = makePackage(root2, 'hyv-beta');
+        rmSync(join(packageDir, 'agents', 'openai.yaml'));
+        assert.throws(() => loadAllFrom(root2), /openai\.yaml/);
+        rmSync(root2, { recursive: true, force: true });
+        const root3 = makeTempRoot();
+        const invalidPackageDir = makePackage(root3, 'hyv-gamma');
+        writeFileSync(join(invalidPackageDir, 'agents', 'openai.yaml'), 'interface:\n  display_name: "unterminated\n  short_description: "test"\n  default_prompt: "Use hyv-gamma"\n');
+        assert.throws(() => loadAllFrom(root3), /supported interface metadata/);
+        rmSync(root3, { recursive: true, force: true });
+    }
+    finally {
+        rmSync(root, { recursive: true, force: true });
+    }
+});
+test('published packages declare command execution and required writes', () => {
+    const packages = loadAll();
+    const writers = new Set(['hyv-profile', 'hyv-hygiene', 'hyv-apply-hidden-text-policy', 'hyv-prepare-rewrite', 'hyv-prepare-judgment', 'hyv-prepare-rebuild', 'hyv-rebuild-writer-request', 'hyv-lifecycle', 'hyv-learning']);
+    for (const [id, pkg] of packages) {
+        assert.ok(pkg.descriptor.permissions.includes('execute_commands'), `${id} must require command execution`);
+        assert.equal(pkg.descriptor.permissions.includes('write_repository'), writers.has(id), `${id} write permission mismatch`);
+    }
+});
+test('published instructions document command-specific argument requirements', () => {
+    const packages = loadAll();
+    assert.match(packages.get('hyv-reduce-judgment').instructions, /hyv reduce-judgment envelope\.json envelope\.json envelope\.json \[envelope\.json\.\.\.\]/);
+    assert.match(packages.get('hyv-learning').instructions, /record-approved/);
+});

package/dist/agents/types.js

@@ -0,0 +1,18 @@
+export const AGENT_SCHEMA_VERSION = '1.0.0';
+export const VALID_PERMISSIONS = new Set([
+    'read_repository',
+    'write_repository',
+    'execute_commands',
+    'network',
+    'browser_automation',
+    'git_write',
+    'pull_request_write',
+    'subagents',
+]);
+export const VALID_UNAVAILABLE_STATUSES = new Set([
+    'NOT_AVAILABLE',
+    'NOT_CONFIGURED',
+    'NOT_RUN',
+    'STALE',
+    'ERROR',
+]);