vgxness 0.1.0

package/LICENSE

@@ -0,0 +1,9 @@
+Proprietary License
+
+Copyright (c) 2026 VGXNESS. All rights reserved.
+
+This package is proprietary software. You may install and use it only as authorized by the copyright holder. No rights are granted to copy, modify, redistribute, sublicense, sell, publish, or make derivative works from this software except under a separate written agreement from the copyright holder.
+
+The npm package contains inspectable JavaScript runtime artifacts for installation and execution. That technical inspectability does not grant an open-source license or redistribution rights.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND NON-INFRINGEMENT.

package/README.md

@@ -0,0 +1,110 @@
+# VGXNESS
+
+VGXNESS is an alpha CLI and MCP control plane for guided AI-agent workflows, SDD artifacts, local memory, and OpenCode integration.
+
+## Alpha status and license
+
+This package is proprietary software. The npm package ships inspectable JavaScript (`dist/`) so Node can run it, but it is **not open-source licensed** and may not be redistributed unless you have written permission. See [LICENSE](./LICENSE).
+
+OpenCode is the primary supported provider in this alpha. Other providers are preview/manual only. The dashboard is read-only/copy-only; provider config writes require explicit CLI confirmation.
+
+## Requirements
+
+- Node.js >= 22
+- npm
+- A platform supported by `better-sqlite3` for your Node/runtime combination
+
+## Install globally
+
+```bash
+npm install -g vgxness
+vgx --help
+vgxness --help
+```
+
+Use the `alpha` npm dist-tag for alpha releases when publishing/consuming pre-release builds.
+
+## First setup with OpenCode
+
+Run the guided setup wizard in a TTY, or preview the same safe setup plan in non-interactive shells:
+
+```bash
+vgx init
+# equivalent explicit command
+vgx setup plan
+```
+
+Defaults for the alpha are: package `vgxness`, provider `opencode`, global user data DB, project OpenCode scope, and `mcp-plus-agents` mode. The generated MCP command for the global DB default is:
+
+```bash
+vgxness mcp start
+```
+
+Apply only after reviewing the plan:
+
+```bash
+vgx setup apply --yes
+```
+
+For project-local or custom databases, use `--db project-local` or `--db custom --db-path <path>` with setup commands. Existing low-level commands remain available:
+
+```bash
+vgxness mcp install opencode --plan
+vgxness mcp install opencode --yes
+```
+
+## Verify
+
+```bash
+vgx doctor
+vgxness mcp doctor opencode
+vgxness setup status
+```
+
+Restart OpenCode after applying config and verify that the `vgxness` MCP server is visible.
+
+## Rollback and recovery
+
+OpenCode applies create a backup before merging existing config. Restore one with:
+
+```bash
+vgx setup rollback --backup <path>
+```
+
+Rollback validates the backup, creates a pre-rollback backup of the current target when present, restores the selected backup byte-for-byte, and keeps the original backup if anything fails. Rerun `vgx doctor` after rollback.
+
+Common issues:
+
+- Node < 22: upgrade Node and reinstall.
+- Native SQLite install failure: verify your platform has compatible `better-sqlite3` binaries/build tools.
+- JSONC or malformed OpenCode config: convert to valid JSON or resolve manually; VGXNESS refuses unsafe rewrites.
+- Existing `mcp.vgxness`: inspect the existing entry before rerunning setup; VGXNESS refuses overwrite by default.
+
+## Release verification matrix
+
+CI and manual release checks target Node 22 on macOS, Linux, and Windows:
+
+```bash
+npm ci
+npm run typecheck
+npm test
+npm run package:release-check
+npm run package:dry-run
+npm run package:smoke:install
+```
+
+Do not publish from CI. Use `npm publish --dry-run --tag alpha` as a final manual gate only.
+
+## Uninstall
+
+```bash
+npm uninstall -g vgxness
+```
+
+Remove any OpenCode config entries and local/global VGXNESS data manually if you no longer need them.
+
+## More docs
+
+- [CLI reference](./docs/cli.md)
+- [Architecture](./docs/architecture.md)
+- [System behavior](./docs/funcionamiento-del-sistema.md)

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

@@ -0,0 +1,144 @@
+import { resolveAgentProfileModel } from './profile-model-routing.js';
+const defaultAgentName = 'vgxness-manager';
+const provider = 'opencode';
+const nextSafeAction = 'review_provider_payload_and_choose_manual_handoff';
+const safety = { executesProvider: false, writesProviderConfig: false, backgroundWorker: false, autonomy: false };
+export class AgentActivationService {
+    dependencies;
+    constructor(dependencies) {
+        this.dependencies = dependencies;
+    }
+    activate(input) {
+        const validated = validateActivationInput(input);
+        if (!validated.ok)
+            return validated;
+        const agent = this.resolveAgent(validated.value);
+        if (!agent.ok)
+            return agent;
+        if (agent.value.mode !== 'agent')
+            return validationFailure('Agent activation requires a top-level agent');
+        const selection = resolveAgentProfileModel({ agent: agent.value, ...(validated.value.providerAdapter === undefined ? {} : { providerAdapter: validated.value.providerAdapter }) });
+        if (!selection.ok)
+            return selection;
+        if (selection.value.providerAdapter !== provider)
+            return validationFailure(`Provider adapter is not supported for activation: ${selection.value.providerAdapter}`);
+        const run = this.dependencies.runs.createRun({
+            project: validated.value.project,
+            userIntent: validated.value.userIntent,
+            workflow: validated.value.workflow,
+            phase: validated.value.phase,
+            selectedAgentId: agent.value.id,
+            providerAdapter: selection.value.providerAdapter,
+            model: selection.value.model,
+        });
+        if (!run.ok)
+            return run;
+        const payload = this.dependencies.opencodeManagerPayload.build(toPayloadInput(validated.value, agent.value.id));
+        if (!payload.ok)
+            return this.failAfterRun(run.value.id, payload.error.code, payload.error.message);
+        const envelopeWithoutRun = {
+            version: 1,
+            agent: { id: agent.value.id, name: agent.value.name, scope: agent.value.scope, mode: 'agent' },
+            provider,
+            modelSelection: selection.value,
+            providerPayload: payload.value,
+            ...(payload.value.skillPayload !== undefined ? { skillsContext: payload.value.skillPayload } : {}),
+            nextSafeAction,
+            safety,
+            warnings: [
+                'Agent activation prepared a provider-ready payload but does not execute providers.',
+                'No provider configuration, background worker, autonomous step, or secrets expansion was performed.',
+                ...selection.value.warnings,
+                ...payload.value.warnings,
+            ],
+        };
+        const checkpoint = this.dependencies.runs.appendCheckpoint({
+            runId: run.value.id,
+            label: 'agent-activation-initial',
+            state: toJson({ ...envelopeWithoutRun, run: { id: run.value.id, status: 'created', checkpointId: null } }),
+        });
+        if (!checkpoint.ok)
+            return this.failAfterRun(run.value.id, checkpoint.error.code, checkpoint.error.message);
+        const event = this.dependencies.runs.appendEvent({
+            runId: run.value.id,
+            kind: 'timeline',
+            title: 'Agent activation prepared',
+            payload: toJson({
+                agent: envelopeWithoutRun.agent,
+                provider,
+                modelSelection: selection.value,
+                nextSafeAction,
+                safety,
+                checkpointId: checkpoint.value.id,
+            }),
+            relatedType: 'run-checkpoint',
+            relatedId: checkpoint.value.id,
+        });
+        if (!event.ok)
+            return this.failAfterRun(run.value.id, event.error.code, event.error.message);
+        return ok({ ...envelopeWithoutRun, run: { id: run.value.id, status: 'created', checkpointId: checkpoint.value.id } });
+    }
+    resolveAgent(input) {
+        if (input.agentId !== undefined)
+            return this.dependencies.agents.getAgent(input.agentId);
+        if (this.dependencies.managerProfiles !== undefined) {
+            const effective = this.dependencies.managerProfiles.resolveEffectiveManager({ project: input.project, scope: input.scope, managerName: defaultAgentName });
+            return effective.ok ? ok(effective.value.manager) : effective;
+        }
+        return this.dependencies.agents.getAgentByName(input.project, input.scope, defaultAgentName);
+    }
+    failAfterRun(runId, code, message) {
+        this.dependencies.runs.appendEvent({
+            runId,
+            kind: 'timeline',
+            title: 'Agent activation failed',
+            payload: { error: { code: String(code), message }, nextSafeActionReturned: false },
+        });
+        this.dependencies.runs.updateFinalStatus({ runId, status: 'failed', outcome: 'failure', outcomeReason: message });
+        return { ok: false, error: { code, message } };
+    }
+}
+function validateActivationInput(input) {
+    if (input.project.trim().length === 0)
+        return validationFailure('Project is required');
+    if (input.userIntent.trim().length === 0)
+        return validationFailure('userIntent is required');
+    if (input.agentId !== undefined && input.agentId.trim().length === 0)
+        return validationFailure('agentId must not be empty');
+    const validated = {
+        project: input.project.trim(),
+        scope: input.scope ?? 'project',
+        userIntent: input.userIntent.trim(),
+        workflow: input.workflow?.trim() || 'agent-activation',
+        phase: input.phase?.trim() || 'activation',
+    };
+    if (input.agentId !== undefined)
+        validated.agentId = input.agentId.trim();
+    if (input.workspaceRoot !== undefined)
+        validated.workspaceRoot = input.workspaceRoot;
+    if (input.maxSourceBytes !== undefined)
+        validated.maxSourceBytes = input.maxSourceBytes;
+    if (input.providerAdapter !== undefined) {
+        if (input.providerAdapter.trim().length === 0)
+            return validationFailure('providerAdapter must not be empty');
+        validated.providerAdapter = input.providerAdapter.trim();
+    }
+    return ok(validated);
+}
+function toPayloadInput(input, agentId) {
+    const payload = { project: input.project, scope: input.scope };
+    if (input.agentId !== undefined)
+        payload.agentId = agentId;
+    else
+        payload.useManagerOverlay = true;
+    if (input.workspaceRoot !== undefined)
+        payload.workspaceRoot = input.workspaceRoot;
+    if (input.maxSourceBytes !== undefined)
+        payload.maxSourceBytes = input.maxSourceBytes;
+    return payload;
+}
+function toJson(value) {
+    return JSON.parse(JSON.stringify(value));
+}
+function ok(value) { return { ok: true, value }; }
+function validationFailure(message) { return { ok: false, error: { code: 'validation_failed', message } }; }

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

@@ -0,0 +1,46 @@
+import { AgentResolver } from './agent-resolver.js';
+import { AgentRepository } from './repositories/agents.js';
+export class AgentRegistryService {
+    database;
+    agents;
+    constructor(database) {
+        this.database = database;
+        this.agents = new AgentRepository(database);
+    }
+    registerAgent(input) {
+        return this.agents.register({ ...input, mode: 'agent' });
+    }
+    registerSubagent(input) {
+        return this.agents.register({ ...input, mode: 'subagent' });
+    }
+    getAgent(id) {
+        return this.agents.getById(id);
+    }
+    getAgentByName(project, scope, name) {
+        return this.agents.getByName(project, scope, name);
+    }
+    listAgents(filters = {}) {
+        return this.agents.list(filters);
+    }
+    listSubagents(parentAgentId) {
+        return this.agents.list({ mode: 'subagent', parentAgentId });
+    }
+    resolveAgents(input) {
+        return new AgentResolver(() => this.listAgentDefinitions(input)).resolve(input);
+    }
+    close() { this.database.close(); }
+    listAgentDefinitions(input) {
+        void input;
+        const summaries = this.agents.list();
+        if (!summaries.ok)
+            return summaries;
+        const definitions = [];
+        for (const summary of summaries.value) {
+            const agent = this.agents.getById(summary.id);
+            if (!agent.ok)
+                return agent;
+            definitions.push(agent.value);
+        }
+        return { ok: true, value: definitions };
+    }
+}

package/dist/agents/agent-resolver.js

@@ -0,0 +1,249 @@
+export class AgentResolver {
+    loadAgents;
+    constructor(loadAgents) {
+        this.loadAgents = loadAgents;
+    }
+    resolve(input) {
+        const agents = this.loadAgents();
+        if (!agents.ok)
+            return agents;
+        const normalized = normalizeInput(input);
+        const candidates = [];
+        const skipped = [];
+        for (const agent of agents.value) {
+            const skipReasons = hardSkipReasons(agent, normalized);
+            if (skipReasons.length > 0) {
+                skipped.push(toSkipped(agent, skipReasons));
+                continue;
+            }
+            const scored = scoreAgent(agent, normalized);
+            if (scored.score <= 0) {
+                skipped.push(toSkipped(agent, ['no matching resolution signals']));
+                continue;
+            }
+            candidates.push(scored);
+        }
+        candidates.sort(compareCandidates);
+        skipped.sort(compareSkipped);
+        return ok({
+            context: {
+                ...(normalized.project !== undefined ? { project: normalized.project } : {}),
+                ...(normalized.scope !== undefined ? { scope: normalized.scope } : {}),
+                ...(normalized.taskDescription !== undefined ? { taskDescription: normalized.taskDescription } : {}),
+                ...(normalized.intent !== undefined ? { intent: normalized.intent } : {}),
+                desiredCapabilities: normalized.desiredCapabilities,
+                ...(normalized.workflow !== undefined ? { workflow: normalized.workflow } : {}),
+                ...(normalized.phase !== undefined ? { phase: normalized.phase } : {}),
+                ...(normalized.providerAdapter !== undefined ? { providerAdapter: normalized.providerAdapter } : {}),
+                ...(normalized.mode !== undefined ? { mode: normalized.mode } : {}),
+            },
+            candidates,
+            skipped,
+        });
+    }
+}
+const SDD_PHASE_SEMANTICS = [
+    {
+        name: 'sdd-planning',
+        phases: ['proposal', 'design', 'tasks'],
+        terms: ['plan', 'planning', 'proposal', 'propose', 'design', 'task', 'tasks', 'breakdown', 'slice', 'slicing'],
+    },
+    {
+        name: 'sdd-verification',
+        phases: ['verify'],
+        terms: ['verify', 'verification', 'test', 'testing', 'review', 'risk', 'evidence'],
+    },
+];
+function normalizeInput(input) {
+    const desiredCapabilities = normalizeList(input.desiredCapabilities ?? []);
+    const taskDescription = normalizeText(input.taskDescription);
+    const intent = normalizeText(input.intent);
+    return {
+        ...input,
+        ...(taskDescription !== undefined ? { taskDescription } : {}),
+        ...(intent !== undefined ? { intent } : {}),
+        desiredCapabilities,
+        terms: tokenize([taskDescription, intent].filter((value) => value !== undefined).join(' ')),
+    };
+}
+function hardSkipReasons(agent, input) {
+    const reasons = [];
+    if (input.project !== undefined && agent.project !== input.project)
+        reasons.push(`project mismatch: ${agent.project}`);
+    if (input.scope !== undefined && agent.scope !== input.scope)
+        reasons.push(`scope mismatch: ${agent.scope}`);
+    if (input.mode !== undefined && agent.mode !== input.mode)
+        reasons.push(`mode mismatch: ${agent.mode}`);
+    if (input.providerAdapter !== undefined && Object.keys(agent.adapters).length > 0 && agent.adapters[input.providerAdapter] === undefined)
+        reasons.push(`provider adapter mismatch: ${input.providerAdapter}`);
+    if ((input.workflow !== undefined || input.phase !== undefined) && agent.workflows.length > 0 && workflowMatches(agent, input).length === 0)
+        reasons.push('workflow mismatch');
+    if (input.desiredCapabilities.length > 0 && matchingValues(agent.capabilities, input.desiredCapabilities).length === 0)
+        reasons.push('capability mismatch');
+    return reasons;
+}
+function scoreAgent(agent, input) {
+    const reasons = [];
+    let score = 0;
+    const capabilityMatches = matchingValues(agent.capabilities, input.desiredCapabilities);
+    if (capabilityMatches.length > 0) {
+        score += capabilityMatches.length * 30;
+        reasons.push(`capabilities matched: ${capabilityMatches.join(', ')}`);
+    }
+    const workflowMatchesValue = workflowSignalMatches(agent, input);
+    if (workflowMatchesValue.exactPhase.length > 0) {
+        score += workflowMatchesValue.exactPhase.length * 25;
+        reasons.push(`workflow phase matched: ${workflowMatchesValue.exactPhase.join(', ')}`);
+    }
+    if (workflowMatchesValue.phaseOnly.length > 0) {
+        score += workflowMatchesValue.phaseOnly.length * 22;
+        reasons.push(`workflow phase-only matched: ${workflowMatchesValue.phaseOnly.join(', ')}`);
+    }
+    if (workflowMatchesValue.broad.length > 0) {
+        score += workflowMatchesValue.broad.length * 20;
+        reasons.push(`workflow matched: ${workflowMatchesValue.broad.join(', ')}`);
+    }
+    if (input.providerAdapter !== undefined) {
+        if (agent.adapters[input.providerAdapter] !== undefined) {
+            score += 20;
+            reasons.push(`provider adapter matched: ${input.providerAdapter}`);
+        }
+        else if (Object.keys(agent.adapters).length === 0) {
+            score += 5;
+            reasons.push(`provider neutral: no adapter restrictions for ${input.providerAdapter}`);
+        }
+    }
+    const skillMatches = matchingValues(agent.skills, [...input.desiredCapabilities, ...input.terms]);
+    if (skillMatches.length > 0) {
+        score += skillMatches.length * 10;
+        reasons.push(`skills matched: ${skillMatches.join(', ')}`);
+    }
+    const textMatches = textSignalMatches(agent, input.terms);
+    if (textMatches.length > 0) {
+        score += Math.min(textMatches.length, 5) * 4;
+        reasons.push(`task text matched: ${textMatches.join(', ')}`);
+    }
+    const phaseSemanticMatches = phaseSemanticMatchesFor(agent, input);
+    for (const match of phaseSemanticMatches) {
+        score += 8;
+        reasons.push(`phase semantics matched: ${match}`);
+    }
+    if (input.mode !== undefined) {
+        score += 3;
+        reasons.push(`mode matched: ${agent.mode}`);
+    }
+    if (agent.mode === 'subagent') {
+        score += 2;
+        reasons.push(`parent constraint satisfied: ${agent.parentAgentId}`);
+    }
+    return { agent, score, reasons };
+}
+function workflowMatches(agent, input) {
+    const matches = workflowSignalMatches(agent, input);
+    return [...matches.broad, ...matches.phaseOnly, ...matches.exactPhase];
+}
+function workflowSignalMatches(agent, input) {
+    const requested = [
+        input.workflow,
+        input.phase,
+        input.workflow !== undefined && input.phase !== undefined ? `${input.workflow}:${input.phase}` : undefined,
+    ].filter((value) => value !== undefined).map(normalizeKey);
+    if (requested.length === 0)
+        return { broad: [], phaseOnly: [], exactPhase: [] };
+    const workflow = input.workflow !== undefined ? normalizeKey(input.workflow) : undefined;
+    const phase = input.phase !== undefined ? normalizeKey(input.phase) : undefined;
+    const exact = workflow !== undefined && phase !== undefined ? `${workflow}:${phase}` : undefined;
+    const matches = { broad: [], phaseOnly: [], exactPhase: [] };
+    for (const agentWorkflow of agent.workflows) {
+        const normalizedWorkflow = normalizeKey(agentWorkflow);
+        if (!requested.includes(normalizedWorkflow))
+            continue;
+        if (exact !== undefined && normalizedWorkflow === exact)
+            matches.exactPhase.push(agentWorkflow);
+        else if (phase !== undefined && normalizedWorkflow === phase)
+            matches.phaseOnly.push(agentWorkflow);
+        else
+            matches.broad.push(agentWorkflow);
+    }
+    return matches;
+}
+function phaseSemanticMatchesFor(agent, input) {
+    const workflow = input.workflow !== undefined ? normalizeKey(input.workflow) : undefined;
+    if (workflow !== undefined && workflow !== 'sdd')
+        return [];
+    const inputPhase = input.phase !== undefined ? normalizeKey(input.phase) : undefined;
+    const agentTerms = tokenize([
+        agent.name,
+        agent.description,
+        ...agent.capabilities,
+        ...agent.skills,
+        ...agent.workflows,
+    ].join(' '));
+    const requestTerms = new Set(input.terms);
+    const matches = [];
+    for (const semantic of SDD_PHASE_SEMANTICS) {
+        const phaseMatches = inputPhase !== undefined && semantic.phases.includes(inputPhase);
+        const termMatches = semantic.terms.some((term) => requestTerms.has(term));
+        const agentMatches = semantic.terms.some((term) => agentTerms.includes(term));
+        if ((phaseMatches || termMatches) && agentMatches)
+            matches.push(semantic.name);
+    }
+    return matches;
+}
+function textSignalMatches(agent, terms) {
+    if (terms.length === 0)
+        return [];
+    const searchable = tokenize([
+        agent.name,
+        agent.description,
+        ...agent.capabilities,
+        ...agent.skills,
+        ...agent.workflows,
+    ].join(' '));
+    return terms.filter((term) => searchable.includes(term));
+}
+function matchingValues(values, requested) {
+    const normalizedValues = new Map(values.map((value) => [normalizeKey(value), value]));
+    const matches = [];
+    for (const requestedValue of requested) {
+        const match = normalizedValues.get(normalizeKey(requestedValue));
+        if (match !== undefined && !matches.includes(match))
+            matches.push(match);
+    }
+    return matches;
+}
+function compareCandidates(a, b) {
+    return b.score - a.score
+        || modeRank(a.agent.mode) - modeRank(b.agent.mode)
+        || a.agent.name.localeCompare(b.agent.name)
+        || a.agent.id.localeCompare(b.agent.id);
+}
+function compareSkipped(a, b) {
+    return a.agent.name.localeCompare(b.agent.name) || a.agent.id.localeCompare(b.agent.id);
+}
+function modeRank(mode) {
+    return mode === 'agent' ? 0 : 1;
+}
+function toSkipped(agent, reasons) {
+    return { agent: { id: agent.id, name: agent.name, mode: agent.mode, project: agent.project, scope: agent.scope }, reasons };
+}
+function normalizeList(values) {
+    return values.map(normalizeText).filter((value) => value !== undefined);
+}
+function normalizeText(value) {
+    const normalized = value?.trim();
+    return normalized ? normalized : undefined;
+}
+function normalizeKey(value) {
+    return value.trim().toLowerCase();
+}
+function tokenize(value) {
+    const seen = new Set();
+    return value.toLowerCase().split(/[^a-z0-9-]+/).filter(Boolean).filter((term) => {
+        if (term.length < 3 || seen.has(term))
+            return false;
+        seen.add(term);
+        return true;
+    });
+}
+function ok(value) { return { ok: true, value }; }