@holdyourvoice/hyv 3.3.4 → 3.4.0

package/dist/agents/catalog.js

@@ -0,0 +1,118 @@
+const CATALOG = {
+    generic: {
+        id: 'generic', display_name: 'Generic coding environment', native_skills: false, subagents: false,
+        hooks: false, blocking_approvals: false, file_edits: false, command_execution: false, browser_automation: false,
+        background_tasks: false, cli: true, repository_read: false,
+        context_capacity: 'host-defined', filesystem_mode: 'host-defined', network_policy: 'host-defined',
+        subagent_isolation: false, session_reset: false, structured_output: false,
+        integration: 'portable Markdown instructions and standalone CLI',
+    },
+    codex: {
+        id: 'codex', display_name: 'Codex', native_skills: true, subagents: true,
+        hooks: false, blocking_approvals: true, file_edits: true, command_execution: true, browser_automation: false,
+        background_tasks: false, cli: true, repository_read: true,
+        context_capacity: 'host-defined', filesystem_mode: 'sandboxed', network_policy: 'approval-gated',
+        subagent_isolation: true, session_reset: true, structured_output: true,
+        integration: 'native skills with AGENTS.md fallback',
+    },
+    'claude-code': {
+        id: 'claude-code', display_name: 'Claude Code', native_skills: true, subagents: true,
+        hooks: true, blocking_approvals: true, file_edits: true, command_execution: true, browser_automation: false,
+        background_tasks: false, cli: true, repository_read: true,
+        context_capacity: 'host-defined', filesystem_mode: 'host-defined', network_policy: 'approval-gated',
+        subagent_isolation: true, session_reset: false, structured_output: true,
+        integration: 'native skills and agent instructions',
+    },
+    cursor: {
+        id: 'cursor', display_name: 'Cursor', native_skills: false, subagents: false,
+        hooks: false, blocking_approvals: false, file_edits: true, command_execution: true, browser_automation: false,
+        background_tasks: false, cli: true, repository_read: true,
+        context_capacity: 'host-defined', filesystem_mode: 'workspace', network_policy: 'host-defined',
+        subagent_isolation: false, session_reset: false, structured_output: false,
+        integration: 'generated rules and portable instructions',
+    },
+    copilot: {
+        id: 'copilot', display_name: 'GitHub Copilot', native_skills: false, subagents: false,
+        hooks: false, blocking_approvals: false, file_edits: true, command_execution: false, browser_automation: false,
+        background_tasks: false, cli: true, repository_read: true,
+        context_capacity: 'host-defined', filesystem_mode: 'workspace', network_policy: 'host-defined',
+        subagent_isolation: false, session_reset: false, structured_output: false,
+        integration: 'repository instructions and custom agent definitions',
+    },
+    'gemini-cli': {
+        id: 'gemini-cli', display_name: 'Gemini CLI', native_skills: false, subagents: false,
+        hooks: false, blocking_approvals: true, file_edits: true, command_execution: true, browser_automation: false,
+        background_tasks: true, cli: true, repository_read: true,
+        context_capacity: 'host-defined', filesystem_mode: 'workspace', network_policy: 'approval-gated',
+        subagent_isolation: false, session_reset: false, structured_output: true,
+        integration: 'terminal-agent instructions and standalone CLI',
+    },
+    'ide-agent': {
+        id: 'ide-agent', display_name: 'IDE coding agent', native_skills: false, subagents: false,
+        hooks: false, blocking_approvals: false, file_edits: true, command_execution: false, browser_automation: false,
+        background_tasks: false, cli: true, repository_read: true,
+        context_capacity: 'host-defined', filesystem_mode: 'workspace', network_policy: 'host-defined',
+        subagent_isolation: false, session_reset: false, structured_output: false,
+        integration: 'generated rules or portable instructions',
+    },
+    windsurf: {
+        id: 'windsurf', display_name: 'Windsurf', native_skills: false, subagents: false,
+        hooks: false, blocking_approvals: false, file_edits: true, command_execution: true, browser_automation: false,
+        background_tasks: false, cli: true, repository_read: true,
+        context_capacity: 'host-defined', filesystem_mode: 'workspace', network_policy: 'host-defined',
+        subagent_isolation: false, session_reset: false, structured_output: false,
+        integration: 'generated workspace rules and standalone CLI',
+    },
+    cline: {
+        id: 'cline', display_name: 'Cline', native_skills: false, subagents: false,
+        hooks: false, blocking_approvals: false, file_edits: true, command_execution: true, browser_automation: false,
+        background_tasks: false, cli: true, repository_read: true,
+        context_capacity: 'host-defined', filesystem_mode: 'workspace', network_policy: 'host-defined',
+        subagent_isolation: false, session_reset: false, structured_output: false,
+        integration: 'generated workspace rules and standalone CLI',
+    },
+    'roo-code': {
+        id: 'roo-code', display_name: 'Roo Code', native_skills: false, subagents: false,
+        hooks: false, blocking_approvals: false, file_edits: true, command_execution: true, browser_automation: false,
+        background_tasks: false, cli: true, repository_read: true,
+        context_capacity: 'host-defined', filesystem_mode: 'workspace', network_policy: 'host-defined',
+        subagent_isolation: false, session_reset: false, structured_output: false,
+        integration: 'generated workspace rules and standalone CLI',
+    },
+};
+export function resolveHost(id) {
+    return CATALOG[id] ?? CATALOG.generic;
+}
+export function listHosts() {
+    return Object.values(CATALOG).sort((a, b) => a.id.localeCompare(b.id));
+}
+function hostSupports(host, permission) {
+    switch (permission) {
+        case 'read_repository': return host.repository_read;
+        case 'write_repository': return host.file_edits;
+        case 'execute_commands': return host.command_execution;
+        case 'network': return false;
+        case 'browser_automation': return host.browser_automation;
+        case 'git_write':
+        case 'pull_request_write': return host.command_execution;
+        case 'subagents': return host.subagents;
+        default: return false;
+    }
+}
+export function runtime(agent, hostID) {
+    const host = resolveHost(hostID);
+    const available = [];
+    const unavailable = [];
+    for (const permission of agent.permissions) {
+        if (hostSupports(host, permission))
+            available.push(permission);
+        else
+            unavailable.push({ capability: permission, status: 'NOT_AVAILABLE' });
+    }
+    let mode = 'procedural';
+    if (unavailable.length > 0)
+        mode = 'prompt-only';
+    if (host.native_skills && unavailable.length === 0)
+        mode = 'native';
+    return { agent, host, available_capabilities: available, unavailable_capabilities: unavailable, execution_mode: mode };
+}

package/dist/agents/catalog.test.js

@@ -0,0 +1,60 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { resolveHost, listHosts, runtime } from './catalog.js';
+import { AGENT_SCHEMA_VERSION } from './types.js';
+function minimalDescriptor(id, permissions) {
+    return {
+        schema_version: AGENT_SCHEMA_VERSION,
+        id,
+        title: id,
+        description: 'test',
+        instruction_file: 'SKILL.md',
+        role: 'Tester',
+        workflow_phase: 'test',
+        input: { required: ['draft'], optional: [] },
+        output: { required: ['report'], optional: [] },
+        evidence_requirements: ['evidence'],
+        permissions,
+        stop_conditions: ['stop'],
+        tool_free_mode: { available: true, behavior: 'report', unavailable_statuses: ['NOT_AVAILABLE'] },
+        handoff_to: [],
+    };
+}
+test('resolves known hosts and falls back to generic for unknown ids', () => {
+    assert.equal(resolveHost('codex').id, 'codex');
+    assert.equal(resolveHost('future-ide').id, 'generic');
+    assert.equal(resolveHost('future-ide').native_skills, false);
+    assert.equal(resolveHost('future-ide').cli, true);
+});
+test('catalog has unique host ids and includes generic', () => {
+    const hosts = listHosts();
+    const ids = hosts.map((host) => host.id);
+    assert.ok(ids.includes('generic'));
+    assert.equal(new Set(ids).size, ids.length);
+});
+test('runtime marks unsupported permissions unavailable and switches to prompt-only', () => {
+    const descriptor = minimalDescriptor('hyv-verify', ['read_repository', 'network', 'subagents']);
+    const resolved = runtime(descriptor, 'generic');
+    assert.deepEqual(resolved.available_capabilities, []);
+    assert.deepEqual(resolved.unavailable_capabilities, [
+        { capability: 'read_repository', status: 'NOT_AVAILABLE' },
+        { capability: 'network', status: 'NOT_AVAILABLE' },
+        { capability: 'subagents', status: 'NOT_AVAILABLE' },
+    ]);
+    assert.equal(resolved.execution_mode, 'prompt-only');
+});
+test('runtime uses native mode when the host supports every permission', () => {
+    const descriptor = minimalDescriptor('hyv-verify', ['read_repository', 'execute_commands']);
+    const resolved = runtime(descriptor, 'codex');
+    assert.deepEqual(resolved.available_capabilities, ['read_repository', 'execute_commands']);
+    assert.deepEqual(resolved.unavailable_capabilities, []);
+    assert.equal(resolved.execution_mode, 'native');
+});
+test('network is never available on any host', () => {
+    for (const host of listHosts()) {
+        const resolved = runtime(minimalDescriptor('hyv-verify', ['network']), host.id);
+        assert.deepEqual(resolved.available_capabilities, []);
+        assert.deepEqual(resolved.unavailable_capabilities, [{ capability: 'network', status: 'NOT_AVAILABLE' }]);
+        assert.equal(resolved.execution_mode, 'prompt-only');
+    }
+});

package/dist/agents/emit.js

@@ -0,0 +1,42 @@
+import { runtime } from './catalog.js';
+export function describe(pkg, hostID) {
+    return runtime(pkg.descriptor, hostID);
+}
+export function emitJson(pkg, hostID) {
+    return JSON.stringify(describe(pkg, hostID), null, 2);
+}
+function printable(values) {
+    return values.length === 0 ? 'none' : values.join(', ');
+}
+function printableUnavailable(values) {
+    return values.length === 0 ? 'none' : values.map(({ capability, status }) => `${capability} (${status})`).join(', ');
+}
+function runtimeSummary(descriptor) {
+    const host = descriptor.host;
+    return `Context capacity: ${host.context_capacity}; filesystem mode: ${host.filesystem_mode}; network policy: ${host.network_policy}; browser/UI: ${host.browser_automation}; subagent isolation: ${host.subagent_isolation}; session reset: ${host.session_reset}; structured output: ${host.structured_output}.`;
+}
+export function emitPrompt(pkg, hostID) {
+    const descriptor = pkg.descriptor;
+    const resolved = describe(pkg, hostID);
+    const lines = [];
+    lines.push(`# ${descriptor.title}`, '');
+    lines.push(`Role: ${descriptor.role}`);
+    lines.push(`Phase: ${descriptor.workflow_phase}`);
+    lines.push(`Execution mode: ${resolved.execution_mode}`, '');
+    lines.push('## Contract', '');
+    lines.push(`Required input: ${printable(descriptor.input.required)}`);
+    lines.push(`Required output: ${printable(descriptor.output.required)}`);
+    lines.push(`Evidence: ${printable(descriptor.evidence_requirements)}`);
+    lines.push(`Stop conditions: ${printable(descriptor.stop_conditions)}`, '');
+    lines.push('## Runtime descriptor', '');
+    lines.push(runtimeSummary(resolved), '');
+    lines.push('## Capability boundary', '');
+    lines.push(`Available: ${printable(resolved.available_capabilities)}`);
+    lines.push(`Unavailable: ${printableUnavailable(resolved.unavailable_capabilities)}`, '');
+    lines.push(`When a capability is unavailable, ${descriptor.tool_free_mode.behavior} Status must be one of: ${printable(descriptor.tool_free_mode.unavailable_statuses)}.`, '');
+    lines.push('## Handoff', '');
+    lines.push(`Next agents: ${printable(descriptor.handoff_to)}`, '');
+    lines.push('## Instructions', '');
+    lines.push(pkg.instructions.trim());
+    return `${lines.join('\n')}\n`;
+}

package/dist/agents/emit.test.js

@@ -0,0 +1,64 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { describe, emitJson, emitPrompt } from './emit.js';
+import { AGENT_SCHEMA_VERSION } from './types.js';
+function makePackage(id) {
+    return {
+        directory: '/pkg',
+        instructions: 'Usage: hyv verify original.md candidate.md profile.json',
+        descriptor: {
+            schema_version: AGENT_SCHEMA_VERSION,
+            id,
+            title: 'hyv-verify',
+            description: 'verify a candidate',
+            instruction_file: 'SKILL.md',
+            role: 'Verifier',
+            workflow_phase: 'verify',
+            input: { required: ['original', 'candidate'], optional: ['writing brief'] },
+            output: { required: ['verification report'], optional: [] },
+            evidence_requirements: ['preserve revision evidence'],
+            permissions: ['read_repository', 'network'],
+            stop_conditions: ['stop when evidence is stale'],
+            tool_free_mode: {
+                available: true,
+                behavior: 'report the decision and exact unavailable capability',
+                unavailable_statuses: ['NOT_AVAILABLE', 'NOT_CONFIGURED', 'NOT_RUN', 'STALE', 'ERROR'],
+            },
+            handoff_to: ['hyv-lifecycle'],
+        },
+    };
+}
+test('describe resolves a host and returns a runtime descriptor', () => {
+    const resolved = describe(makePackage('hyv-verify'), 'codex');
+    assert.equal(resolved.agent.id, 'hyv-verify');
+    assert.equal(resolved.host.id, 'codex');
+    assert.ok(resolved.available_capabilities.includes('read_repository'));
+    assert.deepEqual(resolved.unavailable_capabilities, [{ capability: 'network', status: 'NOT_AVAILABLE' }]);
+    assert.equal(resolved.execution_mode, 'prompt-only');
+});
+test('emitJson renders a valid JSON runtime descriptor', () => {
+    const body = emitJson(makePackage('hyv-verify'), 'generic');
+    const parsed = JSON.parse(body);
+    assert.equal(parsed.agent.id, 'hyv-verify');
+    assert.equal(parsed.host.id, 'generic');
+    assert.ok(Array.isArray(parsed.unavailable_capabilities));
+    assert.deepEqual(parsed.unavailable_capabilities, [
+        { capability: 'read_repository', status: 'NOT_AVAILABLE' },
+        { capability: 'network', status: 'NOT_AVAILABLE' },
+    ]);
+});
+test('emitPrompt includes instructions, capability boundary, and required statuses', () => {
+    const prompt = emitPrompt(makePackage('hyv-verify'), 'codex');
+    assert.match(prompt, /# hyv-verify/);
+    assert.match(prompt, /Role: Verifier/);
+    assert.match(prompt, /Usage: hyv verify original\.md candidate\.md profile\.json/);
+    assert.match(prompt, /Available: read_repository/);
+    assert.match(prompt, /Unavailable: network \(NOT_AVAILABLE\)/);
+    assert.match(prompt, /NOT_AVAILABLE, NOT_CONFIGURED, NOT_RUN, STALE, ERROR/);
+    assert.match(prompt, /Next agents: hyv-lifecycle/);
+});
+test('emitPrompt reports no available capabilities for a fully unavailable host', () => {
+    const prompt = emitPrompt(makePackage('hyv-verify'), 'generic');
+    assert.match(prompt, /Available: none/);
+    assert.match(prompt, /Execution mode: prompt-only/);
+});

package/dist/agents/index.js

@@ -0,0 +1,4 @@
+export { AGENT_SCHEMA_VERSION, VALID_PERMISSIONS, VALID_UNAVAILABLE_STATUSES, } from './types.js';
+export { resolveHost, listHosts, runtime } from './catalog.js';
+export { loadAll, loadAllFrom, sortedIds, validateAll, validateId } from './load.js';
+export { describe, emitJson, emitPrompt } from './emit.js';

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',
+]);

package/dist/approval-capability.js

@@ -1,14 +1,11 @@
 import { createHash, createPublicKey, verify } from 'node:crypto';
 import { parseCanonicalJson } from './canonical-json.js';
+import { exactKeys, isPlainObject as plain } from './internal.js';
 const DIGEST = /^[a-f0-9]{64}$/;
 const BASE64URL = /^[A-Za-z0-9_-]+$/;
 const CLAIM_KEYS = ['version', 'purpose', 'issuer', 'audience', 'subjectArtifactFingerprint', 'sourceHash', 'candidateHash', 'profileId', 'profileRevisionDigest', 'keyId', 'issuedAt', 'notBefore', 'expiresAt', 'nonce'];
 const STORE_KEYS = ['version', 'audience', 'maxCapabilityLifetimeSeconds', 'keys'];
 function fail(error) { return { ok: false, error }; }
-function plain(value) { return value !== null && typeof value === 'object' && !Array.isArray(value) && Object.getPrototypeOf(value) === Object.prototype; }
-function exactKeys(value, required, optional = []) {
-    return required.every((key) => key in value) && Object.keys(value).every((key) => required.includes(key) || optional.includes(key));
-}
 function bounded(value) { return typeof value === 'string' && value.length > 0 && value.length <= 128; }
 function safeTime(value) { return typeof value === 'number' && Number.isSafeInteger(value) && value >= 0; }
 function validClaims(value) {