@holdyourvoice/hyv 3.3.5 → 3.4.0

package/Readme.md

@@ -120,22 +120,32 @@ The tool never edits your draft. You decide which findings are valid, apply the
 | `hyv profile <profile.json> <sample...>` | Two or more text files | Profile JSON |
 | `hyv analyze <draft> <profile.json>` | Draft and profile | Analysis JSON |
 | `hyv hygiene <draft> [--fix] [--output=path]` | Draft | Hygiene report or cleaned copy plus receipt |
+| `hyv inspect-hidden-text <draft> [policy.json]` | Draft and optional policy | Hidden-text inspection report |
+| `hyv apply-hidden-text-policy <draft> <policy.json> <output.md>` | Draft and approved policy | Sanitized output plus receipt |
 | `hyv final-check <path\|->` | Any final text | Accepted text on stdout or a withheld-output report |
+| `hyv logic-lint <draft\|-> [writing-brief.json]` | Draft and optional brief | Deterministic logic-lint report |
 | `hyv rewrite-prompt <draft> <profile.json>` | Draft and profile | Markdown editing brief |
 | `hyv prepare-rewrite <draft> <profile.json> <task.json>` | Draft and profile | Versioned task file |
 | `hyv apply-rewrite <task.json> <response.json> <profile.json>` | Task, response, profile | Candidate evaluation JSON |
 | `hyv prepare-judgment <pre-edit\|post-candidate> <kind> <draft> <profile.json> <task.json> [candidate.md]` | Draft, profile, optional candidate | Versioned judgment task |
 | `hyv reduce-judgment <envelope.json> ...` | Signed judgment envelopes | Recommendation JSON |
 | `hyv prepare-rebuild <draft> <profile.json> <reduction.json> <copy-spec.json> <task.json> [--recomposition-policy policy.json]` | Draft, recommendation, CopySpec, capability, optional policy | Versioned rebuild task |
+| `hyv rebuild-writer-request <task.json> <writer-request.json>` | Rebuild task | Writer-only rebuild request |
 | `hyv apply-rebuild <task.json> <response.json> <profile.json>` | Task, response, profile, capability | Candidate evaluation JSON |
 | `hyv verify <original> <candidate> <profile.json>` | Original, candidate, profile | Verification JSON and exit code |
 | `hyv verify-spec <original> <candidate> <profile.json> <copy-spec.json>` | Original, candidate, profile, CopySpec | Verification JSON with hard claim gate |
-| `hyv learning <show\|inspect\|add\|record\|ratify\|supersede\|migrate\|clear> ...` | Profile, operation, bounded metadata | Preferences or a text-free receipt |
+| `hyv learning <show\|inspect\|add\|record\|record-approved\|ratify\|supersede\|migrate\|clear> ...` | Profile, operation, bounded metadata | Preferences or a text-free receipt |
 | `hyv lifecycle <prepare-semantic\|submit-verdict\|inspect\|validate-final-approval\|finalize> ...` | Versioned lifecycle artifacts | Lifecycle artifact or metadata |
 | `hyv patterns` | None | Ruleset JSON |
+| `hyv mcp` | None | Local MCP server on stdio |
+| `hyv agent list\|validate\|describe\|emit <id> [--host HOST] [--mode prompt\|json] [--output FILE]` | Optional agent id | Portable agent contract (see below) |
 
 Every file argument can be `-` when the command accepts input on standard input. Use `npx @holdyourvoice/hyv <command>` if you have not installed the CLI globally.
 
+## Portable agents
+
+The 23 writing and runtime commands are also model-neutral portable agent packages under `skills/hyv-*/` (an `agent.json` contract, a `SKILL.md`, and an `agents/openai.yaml` interface), mirroring the clean-code portable-agent pattern. `hyv agent list` prints every package; `hyv agent validate [id]` checks the contract schema; `hyv agent describe <id> --host HOST` resolves permissions against a host catalog; and `hyv agent emit <id> --mode prompt|json --host HOST` emits a host-aware contract. The subcommand stays local. `emit --output` creates a new contract file and refuses an existing target. Read the [portable agents guide](docs/wiki/Portable-Agents.md) for the package contract, host model, and examples.
+
 ## Privacy
 
 Your samples, drafts, profiles, and candidates stay on your machine. Verification is read-only. Learning commands can write text-free local events under `~/.hyv/learning/` — profile fingerprint, finding IDs, counts, and an opaque digest. No writing text is uploaded, and the package makes no runtime network requests.
@@ -151,6 +161,7 @@ Keep writing samples, edit histories, and client text out of public commits unle
 | [Prompt contract](docs/PROMPT-CONTRACT.md) | The tier order and editing constraints. |
 | [VoiceDNA](docs/VOICE-DNA.md) | The 13 profile elements. |
 | [Fact linter](docs/wiki/Fact-Linter.md) | The source-consistency checker. |
+| [Portable agents](docs/wiki/Portable-Agents.md) | Load or emit a host-aware contract for one HYV command. |
 | [Support](SUPPORT.md) | Funding without a feature gate. |
 
 ## Contribute

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);
+}