vgxness 0.1.0

package/dist/agents/agent-seed-service.js

@@ -0,0 +1,146 @@
+import { AgentRepository } from './repositories/agents.js';
+const requiredManagerName = 'vgxness-manager';
+export class AgentSeedService {
+    database;
+    agents;
+    constructor(database) {
+        this.database = database;
+        this.agents = new AgentRepository(database);
+    }
+    loadManifest(manifest) {
+        const validation = this.validateManifest(manifest);
+        if (!validation.ok)
+            return validation;
+        const existingNames = new Map();
+        for (const definition of [...manifest.agents, ...manifest.subagents]) {
+            const existing = this.agents.getByName(manifest.project, manifest.scope, definition.name);
+            if (existing.ok)
+                existingNames.set(definition.name, true);
+            else
+                existingNames.set(definition.name, false);
+        }
+        const transaction = this.database.transaction(() => {
+            const agents = [];
+            const subagents = [];
+            const nameToId = new Map();
+            const created = [];
+            const updated = [];
+            for (const definition of manifest.agents) {
+                const registered = this.agents.register(toRegisterInput(manifest, definition, 'agent'));
+                if (!registered.ok)
+                    throw new SeedLoadError(registered.error);
+                agents.push(registered.value);
+                nameToId.set(registered.value.name, registered.value.id);
+                (existingNames.get(definition.name) ? updated : created).push(definition.name);
+            }
+            for (const definition of manifest.subagents) {
+                const parentAgentId = nameToId.get(definition.parentAgentName) ?? this.resolveExistingParentId(manifest, definition.parentAgentName);
+                if (parentAgentId === undefined) {
+                    throw new SeedLoadError({ code: 'validation_failed', message: `Unresolved parentAgentName: ${definition.parentAgentName}` });
+                }
+                const registered = this.agents.register(toRegisterInput(manifest, definition, 'subagent', parentAgentId));
+                if (!registered.ok)
+                    throw new SeedLoadError(registered.error);
+                subagents.push(registered.value);
+                (existingNames.get(definition.name) ? updated : created).push(definition.name);
+            }
+            return { created, updated, agents, subagents, warnings: [] };
+        });
+        if (!transaction.ok) {
+            if (transaction.error.cause instanceof SeedLoadError)
+                return { ok: false, error: transaction.error.cause.failure };
+            return transaction;
+        }
+        return transaction;
+    }
+    validateManifest(manifest) {
+        if (manifest.version !== 1)
+            return validationFailure('Agent seed manifest version must be 1');
+        if (!manifest.project?.trim())
+            return validationFailure('Agent seed manifest project is required');
+        if (manifest.scope !== 'project' && manifest.scope !== 'personal')
+            return validationFailure('Agent seed manifest scope must be project or personal');
+        if (!Array.isArray(manifest.agents))
+            return validationFailure('Agent seed manifest agents must be an array');
+        if (!Array.isArray(manifest.subagents))
+            return validationFailure('Agent seed manifest subagents must be an array');
+        const managerCount = manifest.agents.filter((agent) => agent.name === requiredManagerName).length;
+        if (managerCount !== 1)
+            return validationFailure(`Agent seed manifest must declare exactly one ${requiredManagerName} agent`);
+        const seenNames = new Set();
+        for (const definition of manifest.agents) {
+            const validation = validateDefinition(definition, 'agent');
+            if (!validation.ok)
+                return validation;
+            if (seenNames.has(definition.name))
+                return validationFailure(`Duplicate seed agent name: ${definition.name}`);
+            seenNames.add(definition.name);
+        }
+        for (const definition of manifest.subagents) {
+            const validation = validateDefinition(definition, 'subagent');
+            if (!validation.ok)
+                return validation;
+            if (seenNames.has(definition.name))
+                return validationFailure(`Duplicate seed agent name: ${definition.name}`);
+            seenNames.add(definition.name);
+            if (!definition.parentAgentName.trim())
+                return validationFailure(`Subagent ${definition.name} parentAgentName is required`);
+            if (!manifest.agents.some((agent) => agent.name === definition.parentAgentName) && this.resolveExistingParentId(manifest, definition.parentAgentName) === undefined) {
+                return validationFailure(`Unresolved parentAgentName: ${definition.parentAgentName}`);
+            }
+        }
+        return { ok: true, value: undefined };
+    }
+    resolveExistingParentId(manifest, parentAgentName) {
+        const parent = this.agents.getByName(manifest.project, manifest.scope, parentAgentName);
+        if (!parent.ok || parent.value.mode !== 'agent')
+            return undefined;
+        return parent.value.id;
+    }
+}
+function validateDefinition(definition, mode) {
+    if (!definition.name?.trim())
+        return validationFailure(`Seed ${mode} name is required`);
+    if (!definition.description?.trim())
+        return validationFailure(`Seed ${mode} ${definition.name} description is required`);
+    if (definition.instructions?.kind !== 'inline' && definition.instructions?.kind !== 'path')
+        return validationFailure(`Seed ${mode} ${definition.name} instructions kind is invalid`);
+    if (!definition.instructions.value.trim())
+        return validationFailure(`Seed ${mode} ${definition.name} instructions are required`);
+    return { ok: true, value: undefined };
+}
+function toRegisterInput(manifest, definition, mode, parentAgentId) {
+    const input = {
+        project: manifest.project,
+        scope: manifest.scope,
+        mode,
+        name: definition.name,
+        description: definition.description,
+        instructions: definition.instructions,
+    };
+    if (definition.capabilities !== undefined)
+        input.capabilities = definition.capabilities;
+    if (definition.permissions !== undefined)
+        input.permissions = definition.permissions;
+    if (definition.memory !== undefined)
+        input.memory = definition.memory;
+    if (definition.workflows !== undefined)
+        input.workflows = definition.workflows;
+    if (definition.skills !== undefined)
+        input.skills = definition.skills;
+    if (definition.adapters !== undefined)
+        input.adapters = definition.adapters;
+    if (parentAgentId !== undefined)
+        input.parentAgentId = parentAgentId;
+    return input;
+}
+function validationFailure(message) {
+    return { ok: false, error: { code: 'validation_failed', message } };
+}
+class SeedLoadError extends Error {
+    failure;
+    constructor(failure) {
+        super(failure.message);
+        this.failure = failure;
+    }
+}

package/dist/agents/manager-profile-overlay-service.js

@@ -0,0 +1,34 @@
+export class ManagerProfileOverlayService {
+    dependencies;
+    constructor(dependencies) {
+        this.dependencies = dependencies;
+    }
+    save(input) {
+        return this.dependencies.overlays.save(input);
+    }
+    get(project, scope, managerName) {
+        return this.dependencies.overlays.get(project, scope, managerName);
+    }
+    resolveEffectiveManager(input) {
+        const manager = this.dependencies.agents.getAgentByName(input.project, input.scope, input.managerName);
+        if (!manager.ok)
+            return manager;
+        if (manager.value.mode !== 'agent')
+            return validationFailure('Effective manager requires a top-level agent');
+        const overlay = this.dependencies.overlays.get(input.project, input.scope, input.managerName);
+        if (!overlay.ok) {
+            if (overlay.error.code === 'not_found')
+                return ok({ manager: manager.value });
+            return overlay;
+        }
+        return ok({
+            manager: {
+                ...manager.value,
+                instructions: { kind: 'inline', value: overlay.value.instructions },
+            },
+            overlay: overlay.value,
+        });
+    }
+}
+function ok(value) { return { ok: true, value }; }
+function validationFailure(message) { return { ok: false, error: { code: 'validation_failed', message } }; }

package/dist/agents/profile-model-routing.js

@@ -0,0 +1,26 @@
+export function resolveAgentProfileModel(input) {
+    const providerAdapter = input.providerAdapter?.trim() || 'opencode';
+    const adapters = input.agent.adapters;
+    const adapterNames = Object.keys(adapters);
+    const adapter = adapters[providerAdapter];
+    if (adapterNames.length > 0 && adapter === undefined) {
+        return validationFailure(`Agent ${input.agent.name} does not declare provider adapter: ${providerAdapter}`);
+    }
+    const model = adapter?.model?.trim();
+    if (model !== undefined && model.length > 0) {
+        const profile = profileFromAdapter(adapter?.config);
+        return ok({ providerAdapter, model, ...(profile === undefined ? {} : { profile }), source: 'agent-adapter-model', warnings: [] });
+    }
+    const previewModel = `${providerAdapter}-preview`;
+    const warnings = adapter === undefined
+        ? [`Agent does not declare adapters; using provider-neutral preview model ${previewModel}.`]
+        : [`Adapter ${providerAdapter} does not declare a model; using ${previewModel}.`];
+    const profile = profileFromAdapter(adapter?.config);
+    return ok({ providerAdapter, model: previewModel, ...(profile === undefined ? {} : { profile }), source: 'provider-preview-default', warnings });
+}
+function profileFromAdapter(config) {
+    const profile = config?.profile;
+    return typeof profile === 'string' && profile.trim().length > 0 ? profile.trim() : undefined;
+}
+function ok(value) { return { ok: true, value }; }
+function validationFailure(message) { return { ok: false, error: { code: 'validation_failed', message } }; }

package/dist/agents/renderers/claude-renderer.js

@@ -0,0 +1,98 @@
+import { ok, validationFailure } from './provider-adapter.js';
+const previewWarnings = [
+    'Claude rendering returns preview artifacts only; it does not install or write provider configuration.',
+    'VGX does not execute Claude or run Claude Code from this preview.',
+    'VGX does not install Claude Code, does not write .claude/, does not write CLAUDE.md, and does not write provider configuration.',
+    'VGX does not guarantee exact Claude Code configuration compatibility; this output is a neutral preview only.',
+];
+const previewSafety = {
+    executesProvider: false,
+    writesProviderConfig: false,
+    installable: false,
+    previewOnly: true,
+};
+const claudeCapabilities = {
+    supportedAgentFields: ['name', 'description', 'instructions', 'mode', 'adapter model', 'adapter profile', 'permissions', 'memory', 'skills'],
+    skillInjectionModes: ['included as neutral skill identifiers in preview output'],
+    permissionCategories: ['included as registry permission metadata in preview output'],
+    memoryInjectionModes: ['included as registry memory metadata in preview output'],
+    delegationModel: 'registry agents and subagents are represented in preview output without executing Claude delegation',
+    lifecycleHooks: ['preview render/export only'],
+    configFileLocations: ['rendered/claude/.../claude-preview.json'],
+    limitations: [
+        'Preview artifacts only; does not execute Claude or Claude Code.',
+        'Does not install Claude Code or provider tooling.',
+        'Does not write .claude/, CLAUDE.md, or provider configuration.',
+        'Does not guarantee exact Claude Code configuration compatibility.',
+    ],
+    render: {
+        format: 'claude-json-preview',
+        artifactContentTypes: ['application/json'],
+        installable: false,
+        previewOnly: true,
+    },
+};
+export class ClaudeAgentRenderer {
+    provider = 'claude';
+    capabilities = claudeCapabilities;
+    render(input) {
+        const agents = [input.agent, ...(input.subagents ?? [])];
+        const renderedAgents = {};
+        for (const agent of agents) {
+            const key = claudeAgentKey(agent.name);
+            if (renderedAgents[key] !== undefined)
+                return validationFailure(`Rendered Claude agent key collision: ${key}`);
+            renderedAgents[key] = claudePreviewAgent(agent);
+        }
+        const preview = {
+            version: 1,
+            provider: 'claude',
+            installable: false,
+            compatibility: 'preview-only',
+            agents: renderedAgents,
+            safety: {
+                ...previewSafety,
+                writesClaudeDirectory: false,
+                compatibilityGuaranteed: false,
+            },
+            warnings: previewWarnings,
+        };
+        const artifact = {
+            relativePath: `rendered/claude/${pathSegment(input.agent.project)}/${input.agent.scope}/${pathSegment(input.agent.name)}/claude-preview.json`,
+            contentType: 'application/json',
+            contents: `${JSON.stringify(preview, null, 2)}\n`,
+        };
+        return ok({
+            provider: this.provider,
+            installable: false,
+            artifacts: [artifact],
+            warnings: previewWarnings,
+        });
+    }
+}
+function claudePreviewAgent(agent) {
+    const adapter = claudeAdapter(agent);
+    const rendered = {
+        name: agent.name,
+        description: agent.description,
+        instructions: agent.instructions.value,
+        mode: agent.mode === 'subagent' ? 'subagent' : 'primary',
+        ...(adapter?.model !== undefined ? { model: adapter.model } : {}),
+        permissions: agent.permissions,
+        memory: agent.memory,
+        skills: agent.skills,
+    };
+    const profile = adapter?.config?.profile;
+    if (typeof profile === 'string')
+        rendered.profile = profile;
+    return rendered;
+}
+function claudeAdapter(agent) {
+    return agent.adapters.claude ?? agent.adapters['claude-code'];
+}
+function claudeAgentKey(value) {
+    return pathSegment(value);
+}
+function pathSegment(value) {
+    return value.trim().toLowerCase().replace(/[^a-z0-9._-]+/g, '-').replace(/^-+|-+$/g, '') || 'unnamed';
+}

package/dist/agents/renderers/index.js

@@ -0,0 +1,16 @@
+import { ClaudeAgentRenderer } from './claude-renderer.js';
+import { JsonAgentRenderer } from './json-renderer.js';
+import { OpenCodeAgentRenderer } from './opencode-renderer.js';
+import { ok, validationFailure } from './provider-adapter.js';
+const renderers = {
+    json: new JsonAgentRenderer(),
+    opencode: new OpenCodeAgentRenderer(),
+    claude: new ClaudeAgentRenderer(),
+};
+export function getProviderRenderer(provider) {
+    const normalized = provider.trim().toLowerCase();
+    const renderer = renderers[normalized];
+    return renderer === undefined
+        ? validationFailure(`Unknown provider renderer: ${provider}`)
+        : ok(renderer);
+}

package/dist/agents/renderers/json-renderer.js

@@ -0,0 +1,87 @@
+import { ok, validationFailure } from './provider-adapter.js';
+const previewSafety = {
+    executesProvider: false,
+    writesProviderConfig: false,
+    installable: false,
+    previewOnly: true,
+};
+const jsonCapabilities = {
+    supportedAgentFields: ['id', 'project', 'scope', 'mode', 'name', 'description', 'instructions', 'capabilities', 'permissions', 'memory', 'workflows', 'skills', 'adapters', 'timestamps', 'parentAgentId'],
+    skillInjectionModes: ['preserved as registry metadata in neutral export'],
+    permissionCategories: ['preserved registry permission policy metadata'],
+    memoryInjectionModes: ['preserved registry memory scope metadata'],
+    delegationModel: 'preserves registry agent/subagent relationships without provider delegation execution',
+    lifecycleHooks: ['preview render/export only'],
+    configFileLocations: [],
+    limitations: [
+        'Generic debug/export output; it is not executable provider configuration.',
+        'Does not execute providers or run lifecycle hooks.',
+        'Does not install provider tooling.',
+        'Does not write provider configuration files.',
+    ],
+    render: {
+        format: 'neutral-json-export',
+        artifactContentTypes: ['application/json'],
+        installable: false,
+        previewOnly: true,
+    },
+};
+export class JsonAgentRenderer {
+    provider = 'json';
+    capabilities = jsonCapabilities;
+    render(input) {
+        const subagents = input.subagents ?? [];
+        const basePath = `rendered/json/${pathSegment(input.agent.project)}/${input.agent.scope}/${pathSegment(input.agent.name)}`;
+        const artifacts = [
+            jsonArtifact(`${basePath}.agent.json`, renderedDefinition(input.agent, this.provider)),
+            jsonArtifact(`${basePath}.manifest.json`, {
+                provider: this.provider,
+                installable: false,
+                safety: previewSafety,
+                rootAgentId: input.agent.id,
+                rootAgentName: input.agent.name,
+                subagentIds: subagents.map((subagent) => subagent.id),
+                artifacts: [
+                    `${basePath}.agent.json`,
+                    ...subagents.map((subagent) => `${basePath}.subagents/${pathSegment(subagent.name)}.json`),
+                ],
+            }),
+            ...subagents.map((subagent) => jsonArtifact(`${basePath}.subagents/${pathSegment(subagent.name)}.json`, renderedDefinition(subagent, this.provider))),
+        ];
+        const duplicatePath = firstDuplicate(artifacts.map((artifact) => artifact.relativePath));
+        if (duplicatePath !== undefined)
+            return validationFailure(`Rendered artifact path collision: ${duplicatePath}`);
+        return ok({
+            provider: this.provider,
+            installable: false,
+            artifacts,
+            warnings: ['Rendering returns preview artifacts only; it does not install or write provider configuration.'],
+        });
+    }
+}
+function renderedDefinition(agent, provider) {
+    const rendered = { agent, safety: previewSafety };
+    const selectedAdapter = agent.adapters[provider];
+    if (selectedAdapter !== undefined)
+        rendered.selectedAdapter = selectedAdapter;
+    return rendered;
+}
+function jsonArtifact(relativePath, value) {
+    return {
+        relativePath,
+        contentType: 'application/json',
+        contents: `${JSON.stringify(value, null, 2)}\n`,
+    };
+}
+function pathSegment(value) {
+    return value.trim().toLowerCase().replace(/[^a-z0-9._-]+/g, '-').replace(/^-+|-+$/g, '') || 'unnamed';
+}
+function firstDuplicate(values) {
+    const seen = new Set();
+    for (const value of values) {
+        if (seen.has(value))
+            return value;
+        seen.add(value);
+    }
+    return undefined;
+}

package/dist/agents/renderers/opencode-renderer.js

@@ -0,0 +1,100 @@
+import { ok, validationFailure } from './provider-adapter.js';
+const openCodeSchema = 'https://opencode.ai/config.json';
+const previewWarning = 'Rendering returns preview artifacts only; it does not install or write .opencode/, .claude/, or provider configuration.';
+const previewSafety = {
+    executesProvider: false,
+    writesProviderConfig: false,
+    installable: false,
+    previewOnly: true,
+};
+const openCodeCapabilities = {
+    supportedAgentFields: ['name', 'description', 'instructions', 'mode', 'adapter model', 'adapter config keys: variant, temperature, top_p, hidden, options, color, steps, permission'],
+    skillInjectionModes: ['external preview services may inject skill payloads before rendering; renderer does not resolve skills'],
+    permissionCategories: ['registry permission metadata mapped from adapter permission config'],
+    memoryInjectionModes: ['external preview services may inject memory payloads before rendering; renderer does not load memory'],
+    delegationModel: 'registry agents render as primary agents and registry subagents render as subagents without executing delegation',
+    lifecycleHooks: ['preview render/export only'],
+    configFileLocations: ['rendered/opencode/.../opencode.json'],
+    limitations: [
+        'Preview artifacts only; does not execute OpenCode or provider commands.',
+        'Does not install OpenCode or global tooling.',
+        'Does not write .opencode/, .claude/, or provider configuration.',
+        'Does not provide TUI support or sandbox/worktree enforcement.',
+    ],
+    render: {
+        format: 'opencode-json-preview',
+        artifactContentTypes: ['application/json'],
+        installable: false,
+        previewOnly: true,
+    },
+};
+export class OpenCodeAgentRenderer {
+    provider = 'opencode';
+    capabilities = openCodeCapabilities;
+    render(input) {
+        const agents = [input.agent, ...(input.subagents ?? [])];
+        const renderedAgents = {};
+        for (const agent of agents) {
+            const key = openCodeAgentKey(agent.name);
+            if (renderedAgents[key] !== undefined)
+                return validationFailure(`Rendered OpenCode agent key collision: ${key}`);
+            renderedAgents[key] = openCodeAgentConfig(agent);
+        }
+        const artifact = {
+            relativePath: `rendered/opencode/${pathSegment(input.agent.project)}/${input.agent.scope}/${pathSegment(input.agent.name)}/opencode.json`,
+            contentType: 'application/json',
+            contents: `${JSON.stringify({ '$schema': openCodeSchema, agent: renderedAgents, safety: previewSafety }, null, 2)}\n`,
+        };
+        return ok({
+            provider: this.provider,
+            installable: false,
+            artifacts: [artifact],
+            warnings: [previewWarning, 'Top-level registry agents render as OpenCode primary agents by default; registry subagents render as OpenCode subagents.'],
+        });
+    }
+}
+function openCodeAgentConfig(agent) {
+    const adapter = agent.adapters.opencode;
+    const config = adapter?.config ?? {};
+    const rendered = {
+        ...(adapter?.model !== undefined ? { model: adapter.model } : {}),
+        description: agent.description,
+        prompt: agent.instructions.value,
+        mode: agent.mode === 'subagent' ? 'subagent' : 'primary',
+    };
+    copyString(config, rendered, 'variant');
+    copyNumber(config, rendered, 'temperature');
+    copyNumber(config, rendered, 'top_p');
+    copyBoolean(config, rendered, 'hidden');
+    copyJson(config, rendered, 'options');
+    copyString(config, rendered, 'color');
+    copyNumber(config, rendered, 'steps');
+    copyJson(config, rendered, 'permission');
+    return rendered;
+}
+function copyString(source, target, key) {
+    const value = source[key];
+    if (typeof value === 'string')
+        target[key] = value;
+}
+function copyNumber(source, target, key) {
+    const value = source[key];
+    if (typeof value === 'number')
+        target[key] = value;
+}
+function copyBoolean(source, target, key) {
+    const value = source[key];
+    if (typeof value === 'boolean')
+        target[key] = value;
+}
+function copyJson(source, target, key) {
+    const value = source[key];
+    if (value !== undefined)
+        target[key] = value;
+}
+function openCodeAgentKey(value) {
+    return pathSegment(value);
+}
+function pathSegment(value) {
+    return value.trim().toLowerCase().replace(/[^a-z0-9._-]+/g, '-').replace(/^-+|-+$/g, '') || 'unnamed';
+}

package/dist/agents/renderers/provider-adapter.js

@@ -0,0 +1,6 @@
+export function validationFailure(message) {
+    return { ok: false, error: { code: 'validation_failed', message } };
+}
+export function ok(value) {
+    return { ok: true, value };
+}